Rust Tui Ratatui

Rust TUI Ratatui

Build terminal applications with clear state ownership, predictable rendering, responsive input, and testable UI contracts.

Operating Model

1. Identify whether the app is a true TUI, a CLI with occasional prompts, or a daemon dashboard. Use Ratatui only when persistent terminal state and interactive views are justified. 2. Keep rendering pure: widgets read immutable view models and write to frames. Event handlers mutate application state through explicit actions. 3. Use an app/event/action/update/render shape for nontrivial TUIs. Avoid spreading terminal I/O across widgets. 4. Treat terminal cleanup as reliability-critical. Restore raw mode and alternate screen on all normal and error exits. 5. Preserve accessibility of terminal UX: discoverable keybindings, no required color-only state, clear focus, and deterministic fallback for narrow terminals.

Reference Map

• references/ratatui-app-architecture.md for app structure, state machines, view models, layout, widgets, and theme ownership.
• references/events-async-terminal.md for crossterm, async tasks, cancellation, terminal restoration, and resize handling.
• references/testing-ux.md for buffer assertions, insta snapshots, keybinding tests, and performance checks.

Defaults

• Prefer ratatui with crossterm unless the repository has an established backend.
• Use typed actions/events instead of pushing raw key events through business logic.
• Keep long-running work in tasks; never block the render/input loop on network or disk-heavy operations.
• Use bounded channels and cancellation tokens for background work.
• Use unicode-width or Ratatui text primitives for display width. Do not assume byte length equals terminal width.

Verification

Use focused tests for state transitions and rendering:

cargo fmt --all --check
cargo test --all-targets
cargo clippy --all-targets --all-features -- -D warnings

Add render snapshots for stable screens, action/update tests for key flows, and at least one terminal cleanup path test when introducing a new event loop abstraction.

Events, Async, and Terminal Safety

Event Loop

Use one clear owner for terminal setup and teardown:

• enter alternate screen
• enable raw mode
• install panic/error restoration if needed
• run loop
• restore terminal on every exit path

Avoid early returns between setup and cleanup unless guarded by RAII.

Async Work

Do not block the input/render loop. For async applications:

• Use tokio tasks for network or disk-heavy operations.
• Send task results back as typed events.
• Use bounded channels to avoid unbounded memory growth.
• Use cancellation tokens for work tied to a screen or query.
• Debounce high-frequency inputs such as search.

Ticks and Rendering

Render on meaningful changes where possible. If using ticks, keep the interval intentional and cheap.

Handle resize events explicitly. Recompute layouts and clamp focus/scroll state after size changes.

Error Handling

Terminal restoration is more important than pretty errors. Restore first, then report.

Use domain errors for recoverable failures and keep fatal terminal/runtime errors rare and well explained.

Ratatui App Architecture

Structure

For nontrivial TUIs, use explicit layers:

• App: owns durable state and mode.
• Event: external input such as keys, resize, ticks, task results.
• Action or Message: semantic intent.
• update: transforms state from actions.
• view model: computed display data.
• render: pure frame drawing from state/view model.

This keeps business behavior testable without a terminal and keeps widgets free of hidden side effects.

State and Modes

Represent major screens and modal flows with enums. Avoid boolean clusters such as is_searching, is_editing, is_help_open when only one mode can be active.

Keep focus explicit. For tables/lists, centralize selection state and clamp it after data changes.

Layout

• Use named layout helpers for reused regions.
• Define minimum supported dimensions and fallback views.
• Prefer predictable split constraints over chains of magic percentages.
• Keep theme/style ownership in one module or struct.

Widgets

Custom widgets should be small and deterministic:

• Inputs: immutable state/view model.
• Outputs: draw calls only.
• No direct I/O.
• No spawning tasks.
• No mutation outside documented state objects.

When a widget becomes complex, split data preparation from drawing rather than introducing mutable global UI state.

Domain Integration

Keep domain operations behind services or command objects. The TUI should request work and receive results, not own database clients, HTTP retry policy, or file scanners directly inside render/update functions.

Testing and UX

Tests

Use state/update tests for most behavior:

• keybinding maps to action
• action mutates state
• selection/focus clamps after data changes
• modal transitions are legal
• task results update visible state

Use render tests for stable screens. Ratatui buffers can be compared directly or snapshot-tested with insta after normalizing dynamic content.

Keybindings

• Keep global keys small and documented in-app.
• Avoid conflicting mode-specific keys.
• Provide an obvious quit path.
• Do not require mouse support for primary workflows.

Terminal UX

• Support narrow terminals with fallback layouts.
• Avoid color-only state.
• Preserve scroll position when refreshing data if the selected item still exists.
• Keep loading, empty, and error states first-class.

Performance

Large lists need virtualization or bounded rendering. Avoid reformatting thousands of rows every frame. Precompute expensive strings when data changes, not while drawing.