ratatui-kit

Files (6)

• SKILL.md
• building-polished-uis.md · references/
• components.md · references/
• events-state-routing.md · references/
• hooks.md · references/
• syntax-and-macros.md · references/

SKILL.md (first lines)

# ratatui-kit — Building Terminal UIs in Rust

[ratatui-kit](https://github.com/yexiyue/ratatui-kit) is a component framework for
terminal UIs, built on [Ratatui](https://ratatui.rs) and [Tokio](https://tokio.rs).
If you know React, the mental model transfers almost 1:1: `element!` is JSX,
`#[component]` is a function component, `use_state` is `useState`, `use_future` is
an async effect, props and context work the same way, and there is a built-in
router and global store.

**This framework is niche — do not generate its code from memory.** The macro
syntax, component props, hook signatures, and the input system are specific and
easy to get subtly wrong. Use the minimal template below plus the reference files
in `references/` as your source of truth. A wrong prop name or a hook in the wrong
place is a hard compile error, not a warning.

**Companion skills.** This skill covers the *framework* and assumes general Rust
competence — it does not re-teach ownership, `mut` bindings, borrow rules, or async.
Install **`rust-best-practices`** and **`rust-async-patterns`** alongside it; they
catch the general-Rust mistakes (e.g. a missing `mut` on a mutated binding) that
aren't specific to ratatui-kit. And whatever else you do, **compile before you call
it done** (see *Verifying*) — `cargo check` names every such trivial error precisely.

---

## The build workflow

When asked to build, scaffold, or extend a ratatui-kit UI, work in this order:

1. **Establish the project.**
   - New project: `cargo new <name>`, then add deps (see *Project setup* below).
     Decide which **features** you need — components are feature-gated and won't
     compile if the feature is off. When in doubt, start with `features = ["full"]`.
   - Existing project: check `Cargo.toml` for `ratatui-kit` and which features are
     enabled before using a gated component.

2. **Plan the component tree.** Sketch the screens and panels as `#[component]`
   functions. Decide **state ownership**: ephemeral, per-component state →
   `use_state`; state shared across distant components or pages → an `Atom`
   (`atom` feature). Multi-screen app → `RouterProvider` + `routes!`.

3. **Compose with `element!`.** Build each component's tree. Remember function
   components use **transparent layout**: put layout props (`width`, `height`,
   `flex_direction`, `gap`, …) on the **root element you return**, not on the call
   site of a function component.

4. **Wire input and lifecycle.** Register keyboard/mouse handlers with
   `use_event_handler` (always the same shape — see below). Get the quit callback
   from `use_exit`. Ctrl+C is handled by the framework.

5. **Verify by compiling — this is the definition of done.** Run `cargo check` with
   the features you used, read the errors, and fix them; iterate check → fix → check
   until clean. Most first-compile failures are trivial and the compiler names them
   precisely (a missing `mut` binding, a wrong prop name, an un-enabled feature).
   See *Verifying* at the end. Examples in the repo (`examples/`) are runnable
   references for any pattern.

For anything beyond the essentials on this page, open the matching reference:

| You're working on… | Read |
| --- | --- |
| Which component to use, its exact props/types | `references/components.md` |
| Hook signatures, `State`/`AtomState` methods & operators | `references/hooks.md` |
| `element!` grammar, `#[component]`, `#[derive(Props)]`, `routes!`, adapters | `references/syntax-and-macros.md` |
| Keyboard/mouse events, input layers, state, routing | `references/events-state-routing.md` |
| App skeleton, layout & visual polish, interactive patterns, pitfalls | `references/building-polished-uis.md` |

---

## Project setup

`ratatui-kit` ships **zero features by default**; enable what you use. An async
runtime is required — the docs and examples use Tokio.

```toml
[dependencies]
ratatui-kit = { version = "0.6", features = ["full"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time"] }
```

> **New crate:** set `edition = "2024"` in `[package]` (the crate is edition 2024,
> so an older edition is rejected). If the crate sits inside or beside another Cargo
> workspace, add an empty `[workspace]` table to its `Cargo.toml` so Cargo doesn't
> attach it to the enclosing workspace.

| Feature | Unlocks |
| --- | --- |
| `router` | `RouterProvider` / `Outlet`, `routes!`, `use_navigate` / `use_route` / `use_params` |
| `atom` | `Atom` / `AtomState` / `use_atom` (process-global state) |
| `input` | `Input` / `SearchInput` (single-line text entry) |
| `tree` | `TreeSelect` |
| `virtual-list` | `VirtualList` (windowed list for huge data) |
| `full` | all of the above |

Core components need **no feature**: `View`, `Border`, `Center`, `Fragment`,
`Text`, `WrappedText`, `Positioned`, `Modal`, `ConfirmModal`, `AlertModal`,
`ShortcutInfoModal`, `Select`, `MultiSelect`, `ScrollView`, `ContextProvider`.

> The `textarea` feature is currently offline (its dependency has no Ratatui 0.30
> build). Don't reference `TextArea`.

Standard imports — `prelude::*` for framework items, `ratatui::` for styles/layout
types, `crossterm::event::` for key types:

```rust
use ratatui_kit::{
    crossterm::event::{Event, KeyCode, KeyEventKind},
    prelude::*,
    ratatui::{
        layout::{Constraint, Direction, Flex},
        style::{Color, Style, Stylize},
        text::Line,
    },
};
```

When you build multi-span styled lines, import `Span` too (`text::{Line, Span}`)
rather than writing the fully-qualified path: `Line::from(vec![Span::styled("label ",
Style::new().dark_gray()), Span::styled(value, Style::new().yellow())])`.

From petterssonjonas/tcui, MIT.

More from petterssonjonas/tcui