Learn ratatui-kit

Ratatui Kit’s documentation is organized as a progressive learning path: first build a terminal interface that actually runs, then layer on interaction, state, routing, and component composition, and finally move into the full API reference, built-in components, and advanced escape hatches.

The pacing is inspired by React’s Learn / Reference split and Vue’s Guide / API split: tutorials focus on the everyday 80% you need right now, while reference pages spell out boundaries, parameters, and internal mechanics. Every tutorial in these docs maps to a real example in the repository. When a page needs to show runtime behavior, it uses terminal assets recorded with VHS.

Follow the tutorials

Start with installation, hello_world, and counter; run code as you learn element!, #[component], hooks, input isolation, and routing.

Use reference when needed

Once you start writing real applications, jump into the component model, hooks, input layers, state, routing, and built-in component reference pages.

Use escape hatches last

When the built-in abstractions are not enough, read about custom hooks, providers, hand-written components, and native Ratatui widget bridges.

Recommended path

1. Installation and feature flags: add the crate to a Cargo project and choose a feature set.
2. Quick start: run your first application.
3. Mental model: understand how declarative UI becomes a persistent component tree.
4. Counter tutorial: connect components and async wakeups through a number that increments every second.
5. Async data states: move from local state to requests, loading, errors, and keeping stale data.
6. Atom global state: distinguish local drafts, cross-page shared state, and Router-owned state.
7. Input isolation: let edit layers and modal layers own keyboard events so background components stop competing for input.
8. Routing workspace: enter multi-page app structure, dynamic params, and history.
9. Todo App: combine state, input isolation, and built-in components into a complete workflow.
10. Core model: move into the reference section for details on the component model, hooks, input layers, state, and routing.
11. Built-in components: choose input, modal, list, tree-select, and long-text components by scenario.
12. Advanced customization: learn custom hooks, providers, hand-written components, and native widget bridges.
13. Examples roadmap: inspect how examples, docs pages, and VHS recordings map to each other.

Read it like React / Vue docs

What you want to do now	Matching docs	When to read
Build intuition	start/*	The first time you open the docs
Implement a feature	tutorials/*, apps/todo-app	When you want to code along with an example
Clarify API boundaries	core/*, components/*	Once you know what you want to use
Customize framework capabilities	advanced/*	When built-in components or hooks are not enough
Understand the design	internals/*	When debugging the runtime or contributing to the framework

Documentation principles

• Every tutorial shows a runnable result before explaining concepts.
• Every core concept has a deeper reference page.
• Every example remains truly runnable; commands stay stable even if source files move.
• Every runtime screenshot comes from VHS, not hand-drawn terminal mockups.
• Flowcharts use Mermaid first; conceptual illustrations may use generated images, but they do not replace real runtime assets.