ratatui

name	ratatui
description	Build terminal UIs in Rust with Ratatui. Use when creating TUI applications, immediate-mode rendering, high-performance terminal interfaces, or production Rust CLIs.
effort	medium
allowed-tools	Read, Write, Edit, Bash, Grep

Ratatui (Rust TUI)

Immediate-mode terminal UI framework for Rust using Crossterm backend.

When to Use

• Creating a new TUI application from scratch in Rust
• Adding an interactive terminal interface to an existing CLI tool
• Implementing tabbed navigation, lists, tables, or charts in the terminal
• High-performance terminal rendering where latency matters (e.g., monitoring dashboards)

Keywords: TUI, terminal UI, ratatui, crossterm, interactive CLI, dashboard, ncurses alternative

Workflow

1. Add dependencies to Cargo.toml (ratatui + crossterm)
2. Define App state struct — holds all mutable data (selected index, input buffer, etc.)
3. Initialize terminal — enable raw mode, enter alternate screen
4. Main event loop — terminal.draw(|f| ui(f, &app)) + event::poll + key handler
5. Build UI function — Layout::split → assign chunks → render_widget per chunk
6. Teardown — disable raw mode, leave alternate screen on exit or panic

Dependencies

[dependencies]
ratatui = "0.28"
crossterm = "0.28"

Basic Application

use crossterm::{
    event::{self, Event, KeyCode},
    execute,
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
};
use ratatui::{backend::CrosstermBackend, widgets::{Block, Borders, Paragraph}, Terminal};
use std::io;

struct App {
    counter: i32,
}

impl App {
    fn new() -> App {
        App { counter: 0 }
    }

    fn on_key(&mut self, key: KeyCode) {
        match key {
            KeyCode::Up => self.counter += 1,
            KeyCode::Down => self.counter -= 1,
            _ => {}
        }
    }
}

fn main() -> Result<(), io::Error> {
    enable_raw_mode()?;
    let mut stdout = io::stdout();
    execute!(stdout, EnterAlternateScreen)?;

    let backend = CrosstermBackend::new(stdout);
    let mut terminal = Terminal::new(backend)?;

    let mut app = App::new();

    loop {
        terminal.draw(|f| {
            let block = Block::default().title("Counter").borders(Borders::ALL);
            let paragraph = Paragraph::new(format!("Count: {}", app.counter)).block(block);
            f.render_widget(paragraph, f.area());
        })?;

        if let Event::Key(key) = event::read()? {
            match key.code {
                KeyCode::Char('q') => break,
                code => app.on_key(code),
            }
        }
    }

    disable_raw_mode()?;
    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
    Ok(())
}

Event Loop with Polling

use std::time::Duration;

fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
    loop {
        terminal.draw(|f| ui(f, app))?;

        if event::poll(Duration::from_millis(100))? {
            if let Event::Key(key) = event::read()? {
                match key.code {
                    KeyCode::Char('q') => return Ok(()),
                    KeyCode::Up => app.increment(),
                    KeyCode::Down => app.decrement(),
                    _ => {}
                }
            }
        }
    }
}

Layout

use ratatui::layout::{Constraint, Direction, Layout};

let chunks = Layout::default()
    .direction(Direction::Vertical)
    .constraints([
        Constraint::Length(3),  // Fixed height
        Constraint::Min(0),     // Fill remaining
        Constraint::Length(1),  // Status bar
    ])
    .split(f.area());

References

• Widgets: See references/widgets.md for List, Table, Paragraph, Gauge
• Best Practices: See references/best-practices.md for keyboard, accessibility, performance