Build terminal UIs with ratatui following 2026 Rust best practices. Use when: (1) Creating new TUI apps, (2) Adding widgets/layouts, (3) Keyboard navigation/state management, (4) Image integration via ratatui-image, (5) Async event handling, (6) Shimmer/loading animations via tui-shimmer, (7) Review

Ratatui TUI Development Quick Start 1. Copy template to project: Or generate from the official templates repo: 2. Run : Version Notes (0.30.x) Targets 0.30.x (MSRV 1.88, edition 2024); run cargo info ratatui for the current patch release. Modular workspace : apps keep depending on ratatui ; widget libraries should depend on ratatui core for API stability and fewer dependencies. ratatui::run( terminal ...) : initializes the terminal, installs a panic hook that restores it, runs the closure, and restores on exit. Block::shadow(...) (new in 0.30.1): drop shadows for blocks/popups. Breaking since 0.29 : block::Title removed, layout::Alignment renamed to HorizontalAlignment , Flex::SpaceAround now matches flexbox semantics (use Flex::SpaceEvenly for the old behavior), Marker is non exhaustive. Performance : disabling default features also disables layout cache ; re enable it explicitly or layout performance drops sharply. Template Selection Complexity Template Use Case Minimal hello world Learning, quick demos Simple simple app Single screen apps, tools Async async app Background tasks, network Full component app Multi view, config, logging Decision tree: Need async/network? → async app Multiple screens/components? → component app Just a simple tool? → simple app Learning ratatui? → hello world Project Setup Minimal Cargo.toml Full Dependencies (component app) Release Profile Core Loop: TEA (The Elm Architecture) Styling Rules Use Stylize trait helpers: Color palette: Primary: .cyan() , .green() Error: .red() Warning: .yellow() (sparingly) Muted: .dim() , .dark gray() Accent: .magenta() Text wrapping: See: [references/style guide.md](references/style guide.md) Widget Patterns StatefulWidget Layout Built in State Types ListState for List widget TableState for Table widget ScrollbarState for Scrollbar See: [references/architecture patterns.md](references/architecture patterns.md) Async Event Handling See: [references/async patterns.md](references/async patterns.md) Image Integration Targets ratatui image 11.x; its API changes between majors, so check docs.rs before reusing older snippets. Key points: For portable binaries use chafa static with default features = false ; the default chafa dyn takes precedence when both are enabled Query the protocol once, not per frame Image is stateless and fixed size; all encoding happens in new protocol StatefulImage refits to its render area and encodes at render time, which blocks; drive it through ratatui image::thread::ThreadProtocol (see the crate's examples/thread.rs and examples/tokio.rs ) See: [references/image integration.md](references/image integration.md) Shimmer / Loading Animation [tui shimmer](https://github.com/vinhnx/tui shimmer) sweeps a highlight across text — the "Loading…"/"Thinking…" effect used by coding agent TUIs. Key points: Animation needs redraws: add a tick event (~80 120ms) to the event loop ( select! with tokio::time::interval , or event::poll timeout) Prefer the at phase variant with phase stored in the Model — keeps rendering pure and animation testable True color with automatic fallback for limited terminals API is experimental until 1.0 — pin and review minor bumps Error Handling ratatui::run() / ratatui::init() install a panic hook that restores the terminal before panicking — do not write one by hand. Install color eyre first so the terminal is restored before its report prints: Only write a manual panic hook when constructing Terminal / Backend by hand instead of via ratatui::init() . Error propagation: Release Build Binary at target/release/<name . Size optimization — replaces the Release Profile block above when binary size matters more than speed: Templates Overview hello world (~25 lines) Minimal ratatui demo using ratatui::run() . simple app (~80 lines) Synchronous event loop, App struct, basic render. async app (~120 lines) Tokio runtime, EventStream, select! pattern. component app (~300 lines) Full modular structure: main.rs entry point app.rs App state, update logic event.rs event handling ui.rs rendering action.rs Action enum tui.rs terminal setup config.rs configuration with dirs logging.rs tracing setup Common Patterns Centered Popup With a drop shadow (0.30.1+): Key Bindings Display Status Bar Multi Agent TUI Review Workflow [workflows/tui review.js](workflows/tui review.js) is a dynamic workflow template for Claude Code's Workflow tool. It fans out one reviewer per TUI dimension — TEA architecture, terminal safety, styling, event handling, render performance — then adversarially verifies each finding before reporting, so only confirmed issues survive. In agents without the Workflow tool (Codex), skip the script and apply those five dimensions as a manual review checklist instead. Treat it as a template, not a script to run verbatim : adjust the target path, dimensions, and severity threshold to the codebase. It fans out several agents, so run it when the user asks for a TUI review or a pre release check: Or ask: "run the TUI review workflow from the ratatui tui skill on src/". Checklist Before shipping: [ ] cargo fmt [ ] cargo clippy all features clean [ ] No unwrap() outside tests [ ] Terminal restored on all exit paths ( ratatui::run() or init / restore ) [ ] cargo build release succeeds [ ] Test on target terminal(s)

ratatui-tui