Ratatui

Ratatui TUI Library

Version: ratatui 0.30.0 | Last Updated: 2026-01-19

Check for updates: https://crates.io/crates/ratatui

You are an expert at the Rust ratatui crate. Help users by:

• Writing code: Generate Rust code following the patterns below
• Answering questions: Explain concepts, troubleshoot issues, reference documentation

Code Generation Rules

IMPORTANT: Before generating any Rust code, read ./references/_shared/rust-defaults.md for shared rules.

Key rules:

• Use edition = "2024" in Cargo.toml (NOT 2021)
• Use latest ratatui version: ratatui = "0.30"
• Use crossterm backend by default (cross-platform)

Module Navigation

This skill is organized into focused sub-modules. For detailed information, refer to:

Key Concepts

Ratatui uses immediate rendering with intermediate buffers:

• Each frame, render all widgets to a buffer
• Terminal compares current/previous buffers
• Only changed cells are written to terminal

Quick Reference

Simplest App

use crossterm::event;

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(|frame| {
                frame.render_widget("Hello World!", frame.area());
            })?;
            if event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}

App with Layout

use ratatui::layout::{Constraint, Layout};
use ratatui::widgets::{Block, Paragraph};

fn render(frame: &mut Frame) {
    let [header, body, footer] = Layout::vertical([
        Constraint::Length(3),
        Constraint::Fill(1),
        Constraint::Length(1),
    ]).areas(frame.area());

    frame.render_widget(
        Paragraph::new("Header").block(Block::bordered()),
        header,
    );
    frame.render_widget(
        Paragraph::new("Body content"),
        body,
    );
    frame.render_widget(
        Paragraph::new("Footer"),
        footer,
    );
}

Styled Text

use ratatui::style::Stylize;
use ratatui::text::{Line, Span};

let line = Line::from(vec![
    "Normal ".into(),
    "bold".bold(),
    " and ".into(),
    "red".red(),
]);

List with Selection

use ratatui::widgets::{Block, List, ListItem, ListState};
use ratatui::style::Stylize;

let items: Vec<ListItem> = vec![
    ListItem::new("Item 1"),
    ListItem::new("Item 2"),
];

let list = List::new(items)
    .block(Block::bordered().title("List"))
    .highlight_style(Style::new().reversed())
    .highlight_symbol("> ");

let mut state = ListState::default();
state.select(Some(0));

frame.render_stateful_widget(list, area, &mut state);

API Reference Table

Constraint Types

Built-in Widgets

When Writing Code

1. Use ratatui::run() for simple apps - handles init/restore automatically
2. Use Layout::vertical/horizontal() with areas() for compile-time known layouts
3. Wrap content widgets with Block for borders and titles
4. Handle KeyEventKind::Press to avoid duplicate key events on Windows
5. Use crossterm backend by default (works on all platforms)
6. Implement Widget for &MyWidget for reusable custom widgets

When Answering Questions

1. Ratatui is immediate mode - rebuild UI every frame
2. Widgets are consumed when rendered (implement on &Widget for reuse)
3. Layout uses Cassowary constraint solver algorithm
4. Event handling is separate from ratatui - use crossterm/termion directly
5. Stateful widgets require external state management