Ratatui Patterns
Modern-ratatui knowledge pack. Current stable: ratatui 0.30.2 (2026-06). Model training data predates 0.29. The biggest failure mode is reimplementing by hand what the library now provides; the second is asserting API shapes from memory. Both have the same fix: work from the bundled references, not from memory.
Hard Rules
- Before writing any TUI render/layout/lifecycle code, read
references/modernization-checklist.md. If the thing being built appears in it, use the built-in.
- Before claiming an API exists or writing a signature, verify it in
references/api-reference.md (generated from ratatui source, grep-friendly). If it is not there and not in references/limitations.md, pull live docs (below) before hand-rolling.
- Custom render code is allowed only for needs listed in
references/limitations.md (the verified beyond-API catalog). Anything else custom is a defect.
- Render logic ships with
TestBackend tests per references/testing.md.
- Depend only on the
ratatui umbrella crate, never on ratatui-core/-widgets directly. If default-features = false, re-add layout-cache.
- Mouse events are opt-in.
ratatui::init()/run() do not enable mouse capture; that needs EnableMouseCapture/DisableMouseCapture around the loop (references/api-reference.md §14).
- The event loop can go async (
crossterm's event-stream feature + EventStream for tokio::select!); Terminal::draw stays sync regardless (references/api-reference.md §14).
Files
| file |
when to read |
references/modernization-checklist.md |
always, first: hand-rolled → built-in map + hunt greps |
references/api-reference.md |
exact signatures, feature flags, full widget/API surface, events (mouse capture, sync vs async loop, kitty key flags) |
references/limitations.md |
before writing custom render code; design-system conformance limits |
references/testing.md |
writing or reviewing TUI tests |
references/patterns.md |
composition idioms, corrected cookbook, widget-choice guidance |
references/audit-prompt.md |
fanning out per-repo modernization audits |
Live Docs, on Demand
For anything the bundled references don't answer 1:1, fetch instead of guessing:
- API detail:
https://docs.rs/ratatui/latest/ratatui/ (append module path, e.g. widgets/struct.Table.html)
- release highlights:
https://ratatui.rs/highlights/v0302/ (version digits, no dots)
- breaking changes:
https://raw.githubusercontent.com/ratatui/ratatui/main/BREAKING-CHANGES.md
- concepts/recipes:
https://ratatui.rs/concepts/ and https://ratatui.rs/recipes/
- version check:
curl -s -H 'User-Agent: ratatui-version-check' https://crates.io/api/v1/crates/ratatui (a bare curl without User-Agent gets policy-blocked)
If crates.io reports a version newer than the one at the top of this file, flag it before trusting the bundled references; they get re-synced upstream per release.
Related
- design language (colors, spacing, motion grammar): the project's design-language skill, if it has one. That skill says WHAT it should look like; this one says WHICH ratatui API renders it.
- panic-safe teardown + shimmer recipe: under 0.30,
ratatui::init() already installs the restore panic hook; hand-rolled guards are only for extra seams like bracketed paste or kitty flags. Kitty flags are what let you tell Shift+Enter/Ctrl+Enter apart from plain Enter, see references/api-reference.md §14.
1---2name: ratatui-patterns3description: Modern-ratatui knowledge pack for Rust TUI code on ratatui and crossterm.4---56# Ratatui Patterns78Modern-ratatui knowledge pack. Current stable: **ratatui 0.30.2** (2026-06). Model training data predates 0.29. The biggest failure mode is reimplementing by hand what the library now provides; the second is asserting API shapes from memory. Both have the same fix: **work from the bundled references, not from memory.**910## Hard Rules11121. Before writing any TUI render/layout/lifecycle code, read `references/modernization-checklist.md`. If the thing being built appears in it, use the built-in.132. Before claiming an API exists or writing a signature, verify it in `references/api-reference.md` (generated from ratatui source, grep-friendly). If it is not there and not in `references/limitations.md`, pull live docs (below) before hand-rolling.143. Custom render code is allowed only for needs listed in `references/limitations.md` (the verified beyond-API catalog). Anything else custom is a defect.154. Render logic ships with `TestBackend` tests per `references/testing.md`.165. Depend only on the `ratatui` umbrella crate, never on `ratatui-core`/`-widgets` directly. If `default-features = false`, re-add `layout-cache`.176. Mouse events are opt-in. `ratatui::init()`/`run()` do not enable mouse capture; that needs `EnableMouseCapture`/`DisableMouseCapture` around the loop (`references/api-reference.md` §14).187. The event loop can go async (`crossterm`'s `event-stream` feature + `EventStream` for `tokio::select!`); `Terminal::draw` stays sync regardless (`references/api-reference.md` §14).1920## Files2122| file | when to read |23|---|---|24| `references/modernization-checklist.md` | always, first: hand-rolled → built-in map + hunt greps |25| `references/api-reference.md` | exact signatures, feature flags, full widget/API surface, events (mouse capture, sync vs async loop, kitty key flags) |26| `references/limitations.md` | before writing custom render code; design-system conformance limits |27| `references/testing.md` | writing or reviewing TUI tests |28| `references/patterns.md` | composition idioms, corrected cookbook, widget-choice guidance |29| `references/audit-prompt.md` | fanning out per-repo modernization audits |3031## Live Docs, on Demand3233For anything the bundled references don't answer 1:1, fetch instead of guessing:3435- API detail: `https://docs.rs/ratatui/latest/ratatui/` (append module path, e.g. `widgets/struct.Table.html`)36- release highlights: `https://ratatui.rs/highlights/v0302/` (version digits, no dots)37- breaking changes: `https://raw.githubusercontent.com/ratatui/ratatui/main/BREAKING-CHANGES.md`38- concepts/recipes: `https://ratatui.rs/concepts/` and `https://ratatui.rs/recipes/`39- version check: `curl -s -H 'User-Agent: ratatui-version-check' https://crates.io/api/v1/crates/ratatui` (a bare curl without User-Agent gets policy-blocked)4041If crates.io reports a version newer than the one at the top of this file, flag it before trusting the bundled references; they get re-synced upstream per release.4243## Related4445- design language (colors, spacing, motion grammar): the project's design-language skill, if it has one. That skill says WHAT it should look like; this one says WHICH ratatui API renders it.46- panic-safe teardown + shimmer recipe: under 0.30, `ratatui::init()` already installs the restore panic hook; hand-rolled guards are only for extra seams like bracketed paste or kitty flags. Kitty flags are what let you tell Shift+Enter/Ctrl+Enter apart from plain Enter, see `references/api-reference.md` §14.
uwuclxdy