Ratatui — Terminal User Interface Library for Rust

Introduction

Ratatui is a community fork of tui-rs that has become the standard library for building terminal UIs in Rust. It uses an immediate-mode rendering approach — you describe what the UI should look like each frame, and Ratatui efficiently diffs and updates only what changed. This makes building complex, interactive TUIs surprisingly straightforward.

With over 20,000 GitHub stars, Ratatui powers popular tools like gitui, bottom, kdash, and many other terminal applications. It is the Rust equivalent of Bubble Tea for Go.

What Ratatui Does

Ratatui provides a layout system (constraints-based, like CSS Flexbox) and a rich set of widgets (paragraphs, lists, tables, charts, gauges, tabs, etc.). You compose layouts and widgets each frame, and Ratatui handles terminal manipulation, color rendering, and efficient screen updates via crossterm or termion backends.

Architecture Overview

[Your Application]
State + event handling
        |
   [Ratatui]
   Layout + Widgets
        |
+-------+-------+
|       |       |
[Layout]  [Widgets]
Constraint  Paragraph
Direction   List, Table
Rect        Chart, Gauge
Margin      Tabs, Block
        |
   [Terminal Backend]
   crossterm (cross-platform)
   or termion (Unix)
        |
   [Terminal Emulator]
   Renders ANSI escape codes

Self-Hosting & Configuration

use ratatui::{
    layout::{Constraint, Direction, Layout},
    style::{Color, Modifier, Style},
    widgets::{Block, Borders, List, ListItem, Paragraph, Gauge},
    DefaultTerminal, Frame,
};

struct App {
    items: Vec<String>,
    selected: usize,
    progress: f64,
}

fn ui(frame: &mut Frame, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Vertical)
        .constraints([
            Constraint::Length(3),
            Constraint::Min(5),
            Constraint::Length(3),
        ])
        .split(frame.area());

    // Title
    let title = Paragraph::new("Dashboard")
        .style(Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD))
        .block(Block::default().borders(Borders::ALL));
    frame.render_widget(title, chunks[0]);

    // List
    let items: Vec<ListItem> = app.items.iter()
        .enumerate()
        .map(|(i, item)| {
            let style = if i == app.selected {
                Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)
            } else {
                Style::default()
            };
            ListItem::new(item.as_str()).style(style)
        })
        .collect();
    let list = List::new(items)
        .block(Block::default().title(" Items ").borders(Borders::ALL));
    frame.render_widget(list, chunks[1]);

    // Progress bar
    let gauge = Gauge::default()
        .block(Block::default().title(" Progress ").borders(Borders::ALL))
        .gauge_style(Style::default().fg(Color::Green))
        .ratio(app.progress);
    frame.render_widget(gauge, chunks[2]);
}

Key Features

• Rich Widgets — Paragraph, List, Table, Chart, Gauge, Tabs, Sparkline
• Layout System — constraint-based layouts (like Flexbox)
• Styling — colors, bold, italic, underline, and 256/RGB colors
• Immediate Mode — describe UI each frame, Ratatui handles diffing
• Backend Agnostic — crossterm (cross-platform) or termion (Unix)
• Composable — nest layouts and widgets freely
• Scrolling — built-in scroll state for lists, tables, and text
• Custom Widgets — implement the Widget trait for custom components

Comparison with Similar Tools

FAQ

Q: Ratatui vs tui-rs — what happened? A: Ratatui is a community fork of tui-rs after the original maintainer stepped back. Ratatui is actively maintained with frequent releases and new features. Always use Ratatui for new projects.

Q: How does immediate-mode rendering work? A: Each frame, you describe the entire UI from scratch. Ratatui compares the new frame with the previous one and only sends the differences to the terminal. This makes UI code simple — no manual state tracking for what changed.

Q: Can I use Ratatui for production tools? A: Yes. Tools like gitui (Git TUI), bottom (system monitor), and kdash (Kubernetes dashboard) use Ratatui in production with thousands of users.

Q: How do I handle user input? A: Use crossterm events (event::read()) in your main loop. Match on KeyCode, MouseEvent, or Resize. Ratatui does not handle input — it only renders.

Sources

• GitHub: https://github.com/ratatui/ratatui
• Documentation: https://ratatui.rs
• Examples: https://github.com/ratatui/ratatui/tree/main/examples
• Community fork of tui-rs
• License: MIT