Ratatui

Ratatui is an immediate-mode Rust library for building terminal UIs. It renders the entire UI each frame from application state — there is no persistent widget tree. The default backend is Crossterm.

• Crate: ratatui = "0.30"
• Docs: https://docs.rs/ratatui/latest/ratatui/
• MSRV: 1.86.0 (Rust 2024 edition)
• Widget reference: Read references/widgets.md for built-in widget details, styling, and custom widget implementation
• Architecture patterns: Read references/architecture.md for TEA, component, and monolithic patterns, event handling, layout, state management, and testing

Quick Start

Minimal app with ratatui::run() (v0.30+)

use ratatui::{widgets::{Block, Paragraph}, style::Stylize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| {
                let greeting = Paragraph::new("Hello, Ratatui!")
                    .centered()
                    .yellow()
                    .block(Block::bordered().title("Welcome"));
                frame.render_widget(greeting, frame.area());
            })?;
            if crossterm::event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}

ratatui::run() calls init() before and restore() after the closure — handles terminal setup/teardown automatically.

App with init()/restore() (manual control)

fn main() -> Result<()> {
    color_eyre::install()?;
    let mut terminal = ratatui::init();
    let result = run(&mut terminal);
    ratatui::restore();
    result
}

fn run(terminal: &mut ratatui::DefaultTerminal) -> Result<()> {
    loop {
        terminal.draw(|frame| { /* render widgets */ })?;
        if let Event::Key(key) = crossterm::event::read()? {
            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                break;
            }
        }
    }
    Ok(())
}

Cargo.toml

[dependencies]
ratatui = "0.30"
crossterm = "0.29"
color-eyre = "0.6"

Core Concepts

Rendering

Immediate-mode: call terminal.draw(|frame| { ... }) each tick. Build widgets from state and render — no retained widget tree.

terminal.draw(|frame| {
    frame.render_widget(some_widget, frame.area());
    frame.render_stateful_widget(stateful_widget, area, &mut state);
})?;

Layout

Use Layout to split areas with constraints. Prefer areas() for destructuring (v0.28+):

let [header, body, footer] = Layout::vertical([
    Constraint::Length(3),
    Constraint::Min(0),
    Constraint::Length(1),
]).areas(frame.area());

Centering with Rect::centered() (v0.30+):

let popup_area = frame.area()
    .centered(Constraint::Percentage(60), Constraint::Percentage(40));

Or with Flex::Center:

let [area] = Layout::horizontal([Constraint::Length(40)])
    .flex(Flex::Center)
    .areas(frame.area());

Constraint types: Length(n), Min(n), Max(n), Percentage(n), Ratio(a, b), Fill(weight).

Widgets

All widgets implement Widget trait (fn render(self, area: Rect, buf: &mut Buffer)). Stateful widgets use StatefulWidget with an associated State type.

Built-in: Block, Paragraph, List, Table, Tabs, Gauge, LineGauge, BarChart, Chart, Canvas, Sparkline, Scrollbar, Calendar, Clear.

Text primitives: Span, Line, Text — all implement Widget.

See references/widgets.md for full API details.

Event Handling

Use Crossterm for input. Always check KeyEventKind::Press:

use crossterm::event::{self, Event, KeyCode, KeyEventKind};

if let Event::Key(key) = event::read()? {
    if key.kind == KeyEventKind::Press {
        match key.code {
            KeyCode::Char('q') => should_quit = true,
            KeyCode::Up | KeyCode::Char('k') => scroll_up(),
            KeyCode::Down | KeyCode::Char('j') => scroll_down(),
            _ => {}
        }
    }
}

Terminal Setup & Panic Handling

With ratatui::run() (simplest, v0.30+):

fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| { /* app loop */ })
}

With color-eyre panic hook (recommended for init()/restore()):

fn install_hooks() -> Result<()> {
    let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default().into_hooks();
    let panic_hook = panic_hook.into_panic_hook();
    std::panic::set_hook(Box::new(move |info| {
        ratatui::restore();
        panic_hook(info);
    }));
    eyre_hook.install()?;
    Ok(())
}

Architecture

Choose based on complexity. See references/architecture.md for full patterns with code.

Complexity	Pattern	When
Simple	Monolithic	Single-screen, few key bindings, no async
Medium	TEA (The Elm Architecture)	Multiple modes, form-like interaction
Complex	Component	Multi-panel, reusable panes, plugin-like

TEA (The Elm Architecture) — Summary

struct Model { counter: i32, running: bool }

enum Message { Increment, Decrement, Quit }

fn update(model: &mut Model, msg: Message) {
    match msg {
        Message::Increment => model.counter += 1,
        Message::Decrement => model.counter -= 1,
        Message::Quit => model.running = false,
    }
}

fn view(model: &Model, frame: &mut Frame) {
    let text = format!("Counter: {}", model.counter);
    frame.render_widget(Paragraph::new(text), frame.area());
}

Common Patterns

List Navigation with Selection

let mut list_state = ListState::default().with_selected(Some(0));

// Update
match key.code {
    KeyCode::Up => list_state.select_previous(),
    KeyCode::Down => list_state.select_next(),
    _ => {}
}

// Render
let list = List::new(items)
    .block(Block::bordered().title("Items"))
    .highlight_style(Style::new().reversed())
    .highlight_symbol(Line::from(">> ").bold());
frame.render_stateful_widget(list, area, &mut list_state);

Popup Overlay

fn render_popup(frame: &mut Frame, title: &str, content: &str) {
    let area = frame.area()
        .centered(Constraint::Percentage(60), Constraint::Percentage(40));
    frame.render_widget(Clear, area);
    let popup = Paragraph::new(content)
        .block(Block::bordered().title(title).border_type(BorderType::Rounded))
        .wrap(Wrap { trim: true });
    frame.render_widget(popup, area);
}

Tabbed Interface

let titles = vec!["Tab1", "Tab2", "Tab3"];
let tabs = Tabs::new(titles)
    .block(Block::bordered())
    .select(selected_tab)
    .highlight_style(Style::new().bold().yellow());
frame.render_widget(tabs, tabs_area);

Custom Widget

struct StatusBar { message: String }

impl Widget for StatusBar {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::from(self.message)
            .style(Style::new().bg(Color::DarkGray).fg(Color::White))
            .render(area, buf);
    }
}

// Implement for reference to avoid consuming the widget:
impl Widget for &StatusBar {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::from(self.message.as_str())
            .style(Style::new().bg(Color::DarkGray).fg(Color::White))
            .render(area, buf);
    }
}

Text Input with tui-input

[dependencies]
tui-input = "0.11"

use tui_input::Input;
use tui_input::backend::crossterm::EventHandler;

let mut input = Input::default();

// In event handler:
input.handle_event(&crossterm::event::Event::Key(key));

// In render:
let width = area.width.saturating_sub(2) as usize;
let scroll = input.visual_scroll(width);
let input_widget = Paragraph::new(input.value())
    .scroll((0, scroll as u16))
    .block(Block::bordered().title("Search"));
frame.render_widget(input_widget, area);
frame.set_cursor_position(Position::new(
    area.x + (input.visual_cursor().max(scroll) - scroll) as u16 + 1,
    area.y + 1,
));

Key Conventions

• Always restore terminal — even on panic. Use ratatui::run() or install a panic hook
• Check KeyEventKind::Press on all key events
• Use Block::bordered() as standard container
• Prefer Layout::vertical/horizontal([...]).areas(rect) over .split(rect)
• Use Clear widget before rendering popups/overlays
• Implement Widget for &MyType when the widget should not be consumed on render
• Use ListState, TableState, ScrollbarState for scroll/selection tracking
• Prefer color-eyre for error handling in TUI apps
• Use Rect::centered() (v0.30+) for centering layouts instead of double Flex::Center