ratatui

Ratatui

Write current, compiling Ratatui code (pinned to 0.30.x, Rust 2024) and refuse the stale tui-rs patterns the model remembers from training. The body is the load-bearing 20%: one mental model and one verified example per concept. Everything enumerable — the full widget catalog, every constraint, the streaming model, testing, migration — lives in references/. Open the matching reference before writing nontrivial code in that area.

Mental model

Ratatui is immediate mode: there are no retained widget objects. Every frame you build the whole UI from your own application state and throw it away. A render loop runs terminal.draw(|frame| …); inside, you slice the area into rectangles and draw widgets into them. Ratatui keeps two Buffers and diffs them, writing only the changed cells to the terminal — so redrawing the entire screen every frame is cheap and correct. You own the loop: read an event, update state, draw, repeat.

Four nouns carry everything:

• Terminal — owns the backend (crossterm by default) and the double buffers; gives you a Frame.
• Frame — one frame's drawing surface; frame.area() is the full Rect, frame.render_widget(w, rect) draws.
• Buffer — the grid of styled cells widgets write into. Dimensions are u16 (max 65,535 per side).
• Rect — an x/y/width/height region in u16. Layout is just splitting one Rect into more Rects.

Lifecycle: never hand-roll the terminal

Ratatui sets up raw mode, the alternate screen, and a panic hook for you. Do not call enable_raw_mode, EnterAlternateScreen, or any manual teardown — if you do, a panic or early return leaves the user's terminal wrecked.

fn main() -> color_eyre::Result<()> {
    color_eyre::install()?;            // BEFORE init(): ratatui's panic hook must be outermost,
    let terminal = ratatui::init();    // so it restores the screen before color-eyre prints.
    let result = App::default().run(terminal);
    ratatui::restore();                // always runs; restore BEFORE surfacing the error
    result
}