Terminal UIs with Ratatui

22 min read

Build full-screen, interactive terminal applications in Rust with ratatui — the equivalent of Node’s blessed, ink, or terminal-kit, but with an immediate-mode rendering model that will feel surprisingly close to React’s render function.

Quick Overview

A TUI (Terminal User Interface) is a full-screen, keyboard-driven app that runs inside your terminal: think htop, lazygit, vim, or k9s. In Rust, the dominant library is ratatui (the maintained successor to the unmaintained tui-rs). Its mental model is immediate mode: you do not build a persistent tree of widget objects and mutate them — instead, on every frame you call a single draw closure that describes the entire screen from your application state, and ratatui diffs that description against the previous frame and writes only the changed cells to the terminal. If you have used React, this is the same idea as a render() function: UI as a pure function of state. You pair ratatui with a backend (almost always crossterm) that handles raw mode, the alternate screen, and keyboard/mouse events.

Note: This page covers the ratatui rendering model, widgets, and the event loop. For colored line-oriented output (not full-screen), see Colored Output; for progress bars and spinners, see Progress Bars.

TypeScript/JavaScript Example

In the Node ecosystem, the closest analog is Ink — React for the terminal. You declare components, hold state with hooks, and Ink re-renders when state changes. Here is a small task list with keyboard navigation:

1
// app.tsx — run with: npx tsx app.tsx
2
// deps: ink, react, @types/react
3
import React, { useState } from "react";
4
import { render, Box, Text, useInput, useApp } from "ink";
5

6
const TASKS = ["Write docs", "Review PR", "Fix the build", "Ship it"];
7

8
function App() {
9
  const [selected, setSelected] = useState(0);
10
  const { exit } = useApp();
11

12
  useInput((input, key) => {
13
    if (input === "q" || key.escape) exit();
14
    if (key.downArrow || input === "j") setSelected((i) => (i + 1) % TASKS.length);
15
    if (key.upArrow || input === "k")
16
      setSelected((i) => (i === 0 ? TASKS.length - 1 : i - 1));
17
  });
18

19
  return (
20
    <Box flexDirection="column" borderStyle="round">
21
      {TASKS.map((task, i) => (
22
        <Text key={task} inverse={i === selected}>
23
          {i === selected ? "> " : "  "}
24
          {task}
25
        </Text>
26
      ))}
27
    </Box>
28
  );
29
}
30

31
render(<App />);

Ink hides the event loop entirely: useState triggers re-renders, useInput wires up keyboard handling, and React’s reconciler decides what to repaint. The cost is a heavy dependency tree (React, Yoga layout engine, the reconciler) and the usual JavaScript runtime overhead.

Rust Equivalent

Create a project and add the two crates. cargo new selects the newest stable edition automatically — the current stable toolchain is Rust 1.96.0 on the 2024 edition.

1
cargo new task_tui
2
cd task_tui
3
cargo add ratatui
4
cargo add crossterm

That writes the current versions into Cargo.toml:

1
[dependencies]
2
crossterm = "0.29.0"
3
ratatui = "0.30.0"

Note: ratatui re-exports its default backend, so cargo add ratatui already pulls in crossterm transitively. We add crossterm explicitly because we use its event types (KeyCode, Event) directly.

Here is the same task list in src/main.rs:

1
use std::io;
2
use std::time::Duration;
3

4
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
5
use ratatui::{
6
    DefaultTerminal, Frame,
7
    layout::{Constraint, Direction, Layout},
8
    style::{Color, Modifier, Style},
9
    text::{Line, Span},
10
    widgets::{Block, Borders, List, ListItem, ListState, Paragraph},
11
};
12

13
struct App {
14
    tasks: Vec<String>,
15
    state: ListState,
16
    should_quit: bool,
17
}
18

19
impl App {
20
    fn new() -> Self {
21
        let mut state = ListState::default();
22
        state.select(Some(0));
23
        Self {
24
            tasks: vec![
25
                "Write docs".into(),
26
                "Review PR".into(),
27
                "Fix the build".into(),
28
                "Ship it".into(),
29
            ],
30
            state,
31
            should_quit: false,
32
        }
33
    }
34

35
    fn next(&mut self) {
36
        let i = self.state.selected().map_or(0, |i| (i + 1) % self.tasks.len());
37
        self.state.select(Some(i));
38
    }
39

40
    fn previous(&mut self) {
41
        let i = self.state.selected().map_or(0, |i| {
42
            if i == 0 { self.tasks.len() - 1 } else { i - 1 }
43
        });
44
        self.state.select(Some(i));
45
    }
46
}
47

48
fn main() -> io::Result<()> {
49
    let mut terminal = ratatui::init();
50
    let app = App::new();
51
    let result = run(&mut terminal, app);
52
    ratatui::restore();
53
    result
54
}
55

56
fn run(terminal: &mut DefaultTerminal, mut app: App) -> io::Result<()> {
57
    while !app.should_quit {
58
        terminal.draw(|frame| render(frame, &mut app))?;
59
        handle_events(&mut app)?;
60
    }
61
    Ok(())
62
}
63

64
fn handle_events(app: &mut App) -> io::Result<()> {
65
    if event::poll(Duration::from_millis(100))?
66
        && let Event::Key(key) = event::read()?
67
        && key.kind == KeyEventKind::Press
68
    {
69
        match key.code {
70
            KeyCode::Char('q') | KeyCode::Esc => app.should_quit = true,
71
            KeyCode::Down | KeyCode::Char('j') => app.next(),
72
            KeyCode::Up | KeyCode::Char('k') => app.previous(),
73
            _ => {}
74
        }
75
    }
76
    Ok(())
77
}
78

79
fn render(frame: &mut Frame, app: &mut App) {
80
    let chunks = Layout::default()
81
        .direction(Direction::Vertical)
82
        .constraints([Constraint::Min(1), Constraint::Length(3)])
83
        .split(frame.area());
84

85
    let items: Vec<ListItem> = app
86
        .tasks
87
        .iter()
88
        .map(|t| ListItem::new(Line::from(Span::raw(t))))
89
        .collect();
90

91
    let list = List::new(items)
92
        .block(Block::default().title(" Tasks ").borders(Borders::ALL))
93
        .highlight_style(
94
            Style::default()
95
                .fg(Color::Black)
96
                .bg(Color::Cyan)
97
                .add_modifier(Modifier::BOLD),
98
        )
99
        .highlight_symbol("> ");
100

101
    frame.render_stateful_widget(list, chunks[0], &mut app.state);
102

103
    let help = Paragraph::new("j/k: move   q: quit")
104
        .block(Block::default().borders(Borders::ALL).title(" Help "))
105
        .style(Style::default().add_modifier(Modifier::DIM));
106

107
    frame.render_widget(help, chunks[1]);
108
}

Run it with cargo run. You get a full-screen task list with a highlighted selection, arrow/j/k navigation, and q to quit. On exit, ratatui::restore() puts the terminal back exactly as it was.

Tip: A TUI takes over your terminal, so its visual output cannot be pasted as text here the way a println! can. The code above is compile-verified; later in Best Practices we render a widget to a headless TestBackend and show the real cell buffer it produces.

Detailed Explanation

`ratatui::init()` and `ratatui::restore()`

1
let mut terminal = ratatui::init();
2
// ... run the app ...
3
ratatui::restore();

These two convenience functions (added in ratatui 0.28+) bundle the boilerplate every TUI needs:

init() enables the terminal’s raw mode (so keystrokes arrive immediately, without line-buffering or echo), switches to the alternate screen (a separate full-screen buffer, so your shell scrollback is untouched), installs a panic hook so a crash still restores the terminal, and returns a DefaultTerminal (an alias for Terminal<CrosstermBackend<Stdout>>).
restore() reverses all of that: leaves the alternate screen and disables raw mode.

In the pre-0.28 world you wrote enable_raw_mode(), execute!(stdout, EnterAlternateScreen), and the reverse by hand. You may still see that in older tutorials; init/restore is the current idiom.

Warning: If your program returns or panics between init() and restore() without restoring, the terminal is left in raw mode and your shell becomes unusable (no echo, no newline on Enter). The panic hook installed by init() handles panics; we cover the early-return case in Common Pitfalls.

The draw loop is immediate mode

1
while !app.should_quit {
2
    terminal.draw(|frame| render(frame, &mut app))?;
3
    handle_events(&mut app)?;
4
}

This is the heart of every ratatui app, and the part that surprises developers coming from object-oriented or retained-mode UI toolkits (Qt, GTK, the DOM). You do not create a List object once and call list.setSelected(2) later. Instead, every iteration:

terminal.draw(closure) calls your closure with a fresh Frame. Inside, you construct brand-new widget values from the current app state and render them. These widgets are cheap, short-lived value types — they are dropped at the end of the frame.
ratatui compares the frame’s cell buffer against the previous frame’s buffer (a double buffer) and writes only the differing cells to the terminal. This diffing is why a TUI does not flicker even though you “redraw everything.”
handle_events reads input and mutates app. The next loop iteration renders the new state.

This is exactly React’s model: UI = f(state). Your render function is pure with respect to drawing; all the mutation lives in event handling. The difference from Ink/React is that there is no reconciler and no hidden re-render trigger — you own the loop and decide when to redraw.

Widgets, `Block`, and layout

1
let chunks = Layout::default()
2
    .direction(Direction::Vertical)
3
    .constraints([Constraint::Min(1), Constraint::Length(3)])
4
    .split(frame.area());

frame.area() is the full terminal rectangle (a Rect of { x, y, width, height } in character cells). Layout is ratatui’s flexbox-equivalent: it splits a Rect into sub-rectangles according to Constraints. Here, Length(3) reserves exactly 3 rows for the help box and Min(1) gives the rest to the list. Other constraints include Percentage(50), Ratio(1, 3), Fill(1) (proportional, like flex-grow), and Max(n).

A Block is the chrome around a widget: borders and a title. List, Paragraph, Gauge, etc. each take a .block(...) to draw inside.

Stateful vs. stateless widgets

1
frame.render_stateful_widget(list, chunks[0], &mut app.state);

Most widgets are stateless: render_widget(widget, area) draws them and forgets them. But some widgets need state that survives across frames — a List needs to remember which item is selected and how far it is scrolled, a Table and Scrollbar likewise. That state lives in your App (here ListState), and you hand it in via render_stateful_widget(widget, area, &mut state). The widget reads and updates the state during rendering (for example, adjusting the scroll offset so the selected item stays visible). This split keeps the widget itself a throwaway value while persisting only the minimal data that must outlive a frame.

Event handling with `poll` and `read`

1
if event::poll(Duration::from_millis(100))?
2
    && let Event::Key(key) = event::read()?
3
    && key.kind == KeyEventKind::Press
4
{
5
    match key.code { /* ... */ }
6
}

event::poll(timeout) returns true if an event is waiting, blocking at most timeout. If it returns true, event::read() retrieves the event without blocking. The 100 ms timeout means: redraw at least ten times a second even if no key is pressed (useful for clocks, spinners, or live data). The chained if ... && let ... && ... is a let-chain, stable on the 2024 edition — it replaces the nested if let you would have written on older editions.

Note: Checking key.kind == KeyEventKind::Press matters on Windows, where crossterm reports both key-press and key-release events. Without this filter, every keystroke fires your handler twice. This is one of the most common cross-platform TUI bugs.

Key Differences

Concept	Node (Ink / blessed)	Rust (ratatui)
Rendering model	Retained component tree + React reconciler	Immediate mode: rebuild every widget each frame
What triggers a redraw	`setState` / hooks (automatic)	You call `terminal.draw(...)` in your loop
Widget lifetime	Persistent objects you mutate	Throwaway values constructed per frame
State storage	Component-local (`useState`)	Your own structs; widget “state” (`ListState`) is explicit
Event loop	Hidden by the framework	You own the `loop` and the `poll`/`read` calls
Layout	Yoga (CSS flexbox) in Ink	`Layout` + `Constraint` (flexbox-like, integer cells)
Async / concurrency	Single-threaded event loop	Free to spawn threads or a tokio task; send updates via a channel
Dependencies	React + reconciler + Yoga (large)	ratatui + crossterm (small, no runtime)
Diffing	Virtual DOM diff	Cell-buffer diff (double buffer)

The deepest difference is ownership of the loop. In Ink you never see the loop; in ratatui the loop is your main. This is more code, but it means there is no hidden machinery: you can interleave input, timers, and background-thread messages explicitly, and you can reason precisely about exactly when a redraw happens.

Note: “Immediate mode” describes the API you use, not how the screen is updated. The terminal is still updated incrementally via buffer diffing — ratatui does not repaint every cell every frame. You describe the whole UI each frame; ratatui applies only the deltas.

Common Pitfalls

Returning early without restoring the terminal

If a ? propagates an error or you return between init() and restore(), you skip the restore and leave the terminal in raw mode. The fix is the structure used above: call init(), run a fallible run(...) that returns a Result, always call restore(), and only then propagate the result.

1
fn main() -> std::io::Result<()> {
2
    let mut terminal = ratatui::init();
3
    let result = run(&mut terminal); // may return Err
4
    ratatui::restore();              // runs no matter what
5
    result                           // propagate after restoring
6
}

For 0.30, there is also ratatui::run(|terminal| { ... }), a helper that initializes, runs your closure, and restores even on early return — verified to exist in this version:

1
fn main() -> std::io::Result<()> {
2
    ratatui::run(|terminal| {
3
        // init + restore are handled for you, including on early return
4
        loop {
5
            terminal.draw(|frame| { /* ... */ })?;
6
            break;
7
        }
8
        Ok(())
9
    })
10
}

Using the deprecated `frame.size()`

Older code calls frame.size(); it was renamed to frame.area() and size() is now deprecated. Calling it still compiles but warns:

1
fn render(frame: &mut ratatui::Frame) {
2
    // deprecated: triggers a real compiler warning
3
    frame.render_widget(ratatui::widgets::Paragraph::new("hi"), frame.size());
4
}

The actual warning from cargo build:

1
warning: use of deprecated method `ratatui::Frame::<'_>::size`: use `area()` instead
2
 --> src/main.rs:3:71
3
  |
4
3 |     frame.render_widget(ratatui::widgets::Paragraph::new("hi"), frame.size());
5
  |                                                                       ^^^^
6
  |
7
  = note: `#[warn(deprecated)]` on by default

Use frame.area() instead.

Passing state to `render_widget` instead of `render_stateful_widget`

A List with selection needs render_stateful_widget. If you reach for the wrong method and pass the state as a third argument, you get an arity error — this snippet does not compile:

1
use ratatui::{Frame, widgets::{List, ListState}};
2

3
fn render(frame: &mut Frame, state: &mut ListState) {
4
    let list = List::new(vec!["a", "b"]);
5
    // does not compile (error[E0061]: this method takes 2 arguments but 3 were supplied)
6
    frame.render_widget(list, frame.area(), state);
7
}

The real error from cargo build:

1
error[E0061]: this method takes 2 arguments but 3 arguments were supplied
2
  --> src/main.rs:6:11
3
   |
4
 6 |     frame.render_widget(list, frame.area(), state);
5
   |           ^^^^^^^^^^^^^                     ----- unexpected argument #3 of type `&mut ListState`
6
   |
7
note: method defined here
8
  --> .../ratatui-core-0.1.0/src/terminal/frame.rs:93:12
9
   |
10
93 |     pub fn render_widget<W: Widget>(&mut self, widget: W, area: Rect) {
11
   |            ^^^^^^^^^^^^^
12
help: remove the extra argument
13
   |
14
 6 -     frame.render_widget(list, frame.area(), state);
15
 6 +     frame.render_widget(list, frame.area());
16
   |

The fix is to call frame.render_stateful_widget(list, frame.area(), state).

Blocking the loop with `event::read()` when you need to tick

event::read() blocks until input arrives. If you call it directly in a loop that also needs to animate (a spinner, a clock, live metrics), the screen freezes between keystrokes. Always gate it behind event::poll(timeout)? so the loop wakes up on the timeout to redraw, even when the user is idle.

Forgetting the `KeyEventKind::Press` filter on Windows

As noted above, crossterm delivers both press and release key events on Windows. Code tested only on macOS/Linux will appear to “double-press” on Windows. Filter on key.kind == KeyEventKind::Press.

Best Practices

Separate state, update, and view. Keep an App struct (state), free functions or methods that mutate it in response to events (update), and a pure render/ui function that only reads state and draws (view). This is the Elm/React architecture and it makes a TUI testable.

Make rendering a pure function so you can test it headlessly. ratatui ships a TestBackend that renders into an in-memory cell grid with no real terminal — perfect for unit tests and CI. Here is a self-contained program that renders a greeting into a 20×3 buffer and prints the cells it produced:

1
use ratatui::{
2
    Terminal,
3
    backend::TestBackend,
4
    widgets::{Block, Paragraph},
5
};
6

7
fn draw_greeting(name: &str) -> Terminal<TestBackend> {
8
    let backend = TestBackend::new(20, 3);
9
    let mut terminal = Terminal::new(backend).unwrap();
10
    terminal
11
        .draw(|frame| {
12
            let p = Paragraph::new(format!("Hi {name}")).block(Block::bordered());
13
            frame.render_widget(p, frame.area());
14
        })
15
        .unwrap();
16
    terminal
17
}
18

19
fn main() {
20
    let terminal = draw_greeting("Ada");
21
    let buffer = terminal.backend().buffer();
22
    let row0: String = (0..20).map(|x| buffer[(x, 0)].symbol()).collect();
23
    let row1: String = (0..20).map(|x| buffer[(x, 1)].symbol()).collect();
24
    println!("{row0}");
25
    println!("{row1}");
26
}

Running it with cargo run prints the actual rendered cells:

1
┌──────────────────┐
2
│Hi Ada            │

You can assert against an expected buffer with Buffer::with_lines, which keeps tests readable. See Section 13: Testing for the broader testing toolkit.

Prefer the Stylize shorthands for terse styling. Instead of Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD), import ratatui::style::Stylize and write .blue().bold() directly on strings and widgets: "Counter".bold(), Block::bordered().blue(), Paragraph::new(text).centered().
Use a tick rate to decouple input latency from animation. Compute the poll timeout from tick_rate - last_tick.elapsed() so you redraw on a steady cadence while still responding to keys instantly. The Real-World Example does exactly this.
For long-running work, do it on a thread and send updates over a channel. ratatui’s loop must stay responsive. Spawn a std::thread (or a tokio task — see Section 11: Async) for I/O or computation, send progress via an mpsc channel, and try_recv it in your loop to update state. For pure progress reporting outside a TUI, indicatif is simpler.
Respect terminal capabilities. Not every terminal supports truecolor or every Unicode box-drawing glyph. ratatui degrades gracefully, but for color-sensitive output also honor the NO_COLOR convention — see Colored Output.

Real-World Example

A compact service monitor (a tiny k9s/htop): a tab bar, a stateful list of services on the left, a load gauge for the selected service on the right, a footer with key hints, and a tick-based update that simulates live metrics. This is fully compile-verified and clippy-clean.

1
use std::io;
2
use std::time::{Duration, Instant};
3

4
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
5
use ratatui::{
6
    DefaultTerminal, Frame,
7
    layout::{Constraint, Layout},
8
    style::{Color, Modifier, Style, Stylize},
9
    text::Line,
10
    widgets::{Block, Gauge, List, ListItem, ListState, Tabs},
11
};
12

13
/// A single monitored service and its simulated load.
14
struct Service {
15
    name: String,
16
    load: u16, // 0..=100
17
}
18

19
struct App {
20
    services: Vec<Service>,
21
    selected: ListState,
22
    tab: usize,
23
    last_tick: Instant,
24
    should_quit: bool,
25
}
26

27
impl App {
28
    fn new() -> Self {
29
        let mut selected = ListState::default();
30
        selected.select(Some(0));
31
        Self {
32
            services: vec![
33
                Service { name: "api-gateway".into(), load: 22 },
34
                Service { name: "auth-service".into(), load: 64 },
35
                Service { name: "worker-pool".into(), load: 81 },
36
                Service { name: "postgres".into(), load: 35 },
37
            ],
38
            selected,
39
            tab: 0,
40
            last_tick: Instant::now(),
41
            should_quit: false,
42
        }
43
    }
44

45
    /// Advance simulated state. In a real app this is where you poll metrics.
46
    fn on_tick(&mut self) {
47
        for (i, svc) in self.services.iter_mut().enumerate() {
48
            let delta = ((self.last_tick.elapsed().as_millis() / 50) as u16 + i as u16) % 7;
49
            svc.load = (svc.load + delta) % 101;
50
        }
51
    }
52

53
    fn select_next(&mut self) {
54
        let i = self.selected.selected().map_or(0, |i| (i + 1) % self.services.len());
55
        self.selected.select(Some(i));
56
    }
57
}
58

59
const TICK_RATE: Duration = Duration::from_millis(250);
60

61
fn main() -> io::Result<()> {
62
    let mut terminal = ratatui::init();
63
    let result = run(&mut terminal, App::new());
64
    ratatui::restore();
65
    result
66
}
67

68
fn run(terminal: &mut DefaultTerminal, mut app: App) -> io::Result<()> {
69
    while !app.should_quit {
70
        terminal.draw(|frame| ui(frame, &mut app))?;
71

72
        // Wake up at least every tick so the gauges animate even when idle.
73
        let timeout = TICK_RATE.saturating_sub(app.last_tick.elapsed());
74
        if event::poll(timeout)?
75
            && let Event::Key(key) = event::read()?
76
            && key.kind == KeyEventKind::Press
77
        {
78
            match key.code {
79
                KeyCode::Char('q') | KeyCode::Esc => app.should_quit = true,
80
                KeyCode::Tab => app.tab = (app.tab + 1) % 2,
81
                KeyCode::Down | KeyCode::Char('j') => app.select_next(),
82
                _ => {}
83
            }
84
        }
85
        if app.last_tick.elapsed() >= TICK_RATE {
86
            app.on_tick();
87
            app.last_tick = Instant::now();
88
        }
89
    }
90
    Ok(())
91
}
92

93
fn ui(frame: &mut Frame, app: &mut App) {
94
    let [header, body, footer] = Layout::vertical([
95
        Constraint::Length(3),
96
        Constraint::Min(0),
97
        Constraint::Length(1),
98
    ])
99
    .areas(frame.area());
100

101
    // Header: tab bar.
102
    let tabs = Tabs::new(vec!["Services", "Logs"])
103
        .block(Block::bordered().title(" monitor "))
104
        .select(app.tab)
105
        .highlight_style(Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD));
106
    frame.render_widget(tabs, header);
107

108
    // Body: split into a list (left) and a gauge (right).
109
    let [left, right] =
110
        Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]).areas(body);
111

112
    let items: Vec<ListItem> = app
113
        .services
114
        .iter()
115
        .map(|s| ListItem::new(Line::from(format!("{:<14} {:>3}%", s.name, s.load))))
116
        .collect();
117
    let list = List::new(items)
118
        .block(Block::bordered().title(" Services "))
119
        .highlight_style(Style::default().bg(Color::Blue).fg(Color::White))
120
        .highlight_symbol("> ");
121
    frame.render_stateful_widget(list, left, &mut app.selected);
122

123
    let idx = app.selected.selected().unwrap_or(0);
124
    let svc = &app.services[idx];
125
    let color = if svc.load > 75 { Color::Red } else { Color::Green };
126
    let gauge = Gauge::default()
127
        .block(Block::bordered().title(format!(" {} load ", svc.name)))
128
        .gauge_style(color)
129
        .percent(svc.load);
130
    frame.render_widget(gauge, right);
131

132
    let footer_line = Line::from(" Tab: switch   j/↓: next   q: quit ").dim();
133
    frame.render_widget(footer_line, footer);
134
}

Things worth highlighting:

The tick rate decouples redraw cadence from input. event::poll(timeout) blocks for at most the time remaining until the next tick, so keys feel instant while the gauges animate four times a second.
Layout::vertical([...]).areas(rect) returns a fixed-size array you destructure directly into [header, body, footer] — cleaner than indexing chunks[0], chunks[1].
The gauge color is recomputed from state every frame (red above 75%, green below). That is immediate mode in one line: the view is a pure function of svc.load.
Only the ListState persists across frames; every widget value is rebuilt each ui call and dropped at frame end.

Exercises

Exercise 1: A counter app

Difficulty: Beginner

Objective: Internalize the draw loop by building the smallest possible interactive TUI.

Instructions: Create a TUI that displays a single integer counter centered on screen inside a bordered block. Pressing + or Up increments it, - or Down decrements it, and q quits. Use ratatui::init()/restore() and the Stylize shorthands (.bold(), .centered()).

Solution

1
use std::io;
2

3
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
4
use ratatui::{
5
    DefaultTerminal, Frame,
6
    style::Stylize,
7
    widgets::{Block, Paragraph},
8
};
9

10
fn main() -> io::Result<()> {
11
    let mut terminal = ratatui::init();
12
    let result = run(&mut terminal);
13
    ratatui::restore();
14
    result
15
}
16

17
fn run(terminal: &mut DefaultTerminal) -> io::Result<()> {
18
    let mut counter: i64 = 0;
19
    loop {
20
        terminal.draw(|frame: &mut Frame| {
21
            let text = format!("Counter: {counter}\n\n(+/-: change, q: quit)");
22
            let widget = Paragraph::new(text)
23
                .block(Block::bordered().title(" Counter ".bold()))
24
                .centered()
25
                .blue();
26
            frame.render_widget(widget, frame.area());
27
        })?;
28

29
        if let Event::Key(key) = event::read()?
30
            && key.kind == KeyEventKind::Press
31
        {
32
            match key.code {
33
                KeyCode::Char('q') => return Ok(()),
34
                KeyCode::Char('+') | KeyCode::Up => counter += 1,
35
                KeyCode::Char('-') | KeyCode::Down => counter -= 1,
36
                _ => {}
37
            }
38
        }
39
    }
40
}

Because there is no animation, this version blocks on event::read() directly — no poll needed. It only redraws when a key is pressed.

Exercise 2: A chat-style input box

Difficulty: Intermediate

Objective: Manage editable text state and a two-pane layout.

Instructions: Build a TUI with a vertical layout: a scrolling List of submitted messages on top, and a single-line input box (3 rows, bordered) at the bottom. Typing appends characters to the input; Backspace removes the last character; Enter pushes the current input into the message list and clears it; Esc quits. Empty input on Enter should do nothing.

Solution

1
use std::io;
2

3
use crossterm::event::{self, Event, KeyCode, KeyEventKind};
4
use ratatui::{
5
    DefaultTerminal, Frame,
6
    layout::{Constraint, Layout},
7
    style::Stylize,
8
    widgets::{Block, List, ListItem, Paragraph},
9
};
10

11
struct App {
12
    input: String,
13
    messages: Vec<String>,
14
    should_quit: bool,
15
}
16

17
fn main() -> io::Result<()> {
18
    let mut terminal = ratatui::init();
19
    let app = App { input: String::new(), messages: Vec::new(), should_quit: false };
20
    let result = run(&mut terminal, app);
21
    ratatui::restore();
22
    result
23
}
24

25
fn run(terminal: &mut DefaultTerminal, mut app: App) -> io::Result<()> {
26
    while !app.should_quit {
27
        terminal.draw(|frame| ui(frame, &app))?;
28
        if let Event::Key(key) = event::read()?
29
            && key.kind == KeyEventKind::Press
30
        {
31
            match key.code {
32
                KeyCode::Esc => app.should_quit = true,
33
                KeyCode::Enter => {
34
                    if !app.input.is_empty() {
35
                        app.messages.push(std::mem::take(&mut app.input));
36
                    }
37
                }
38
                KeyCode::Backspace => {
39
                    app.input.pop();
40
                }
41
                KeyCode::Char(c) => app.input.push(c),
42
                _ => {}
43
            }
44
        }
45
    }
46
    Ok(())
47
}
48

49
fn ui(frame: &mut Frame, app: &App) {
50
    let [list_area, input_area] =
51
        Layout::vertical([Constraint::Min(0), Constraint::Length(3)]).areas(frame.area());
52

53
    let items: Vec<ListItem> =
54
        app.messages.iter().map(|m| ListItem::new(m.as_str())).collect();
55
    let list = List::new(items).block(Block::bordered().title(" Messages "));
56
    frame.render_widget(list, list_area);
57

58
    let input = Paragraph::new(app.input.as_str())
59
        .block(Block::bordered().title(" Type, Enter to send, Esc to quit "))
60
        .yellow();
61
    frame.render_widget(input, input_area);
62
}

Note std::mem::take(&mut app.input) moves the current String out (leaving an empty one) and pushes it without cloning — idiomatic and allocation-free.

Exercise 3: Test a render function headlessly

Difficulty: Advanced

Objective: Prove your view is a pure function of state by testing it with TestBackend — no real terminal involved.

Instructions: Write a function render_status(frame: &mut Frame, connected: bool) that draws "ONLINE" when connected is true and "OFFLINE" otherwise. Then write two #[test]s that render it into a 1-row TestBackend and assert the resulting buffer equals the expected text using Buffer::with_lines. Confirm cargo test passes.

Solution

1
use ratatui::{Frame, widgets::Paragraph};
2

3
fn render_status(frame: &mut Frame, connected: bool) {
4
    let text = if connected { "ONLINE" } else { "OFFLINE" };
5
    frame.render_widget(Paragraph::new(text), frame.area());
6
}
7

8
fn main() {
9
    println!("run `cargo test` for the headless render tests");
10
}
11

12
#[cfg(test)]
13
mod tests {
14
    use super::*;
15
    use ratatui::{Terminal, backend::TestBackend, buffer::Buffer};
16

17
    fn render_to_buffer(connected: bool, w: u16) -> Buffer {
18
        let mut terminal = Terminal::new(TestBackend::new(w, 1)).unwrap();
19
        terminal
20
            .draw(|frame| render_status(frame, connected))
21
            .unwrap();
22
        terminal.backend().buffer().clone()
23
    }
24

25
    #[test]
26
    fn shows_online_when_connected() {
27
        let buffer = render_to_buffer(true, 7);
28
        assert_eq!(buffer, Buffer::with_lines(["ONLINE "]));
29
    }
30

31
    #[test]
32
    fn shows_offline_when_disconnected() {
33
        let buffer = render_to_buffer(false, 7);
34
        assert_eq!(buffer, Buffer::with_lines(["OFFLINE"]));
35
    }
36
}

Running cargo test produces the real output:

1
running 2 tests
2
test tests::shows_offline_when_disconnected ... ok
3
test tests::shows_online_when_connected ... ok
4

5
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

The "ONLINE " literal has a trailing space because the buffer is 7 cells wide and "ONLINE" is 6 characters; the unused cell renders as a space. This is exactly the kind of off-by-one a headless test catches before it ships.

Terminal UIs with Ratatui

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

ratatui::init() and ratatui::restore()

The draw loop is immediate mode

Widgets, Block, and layout

Stateful vs. stateless widgets

Event handling with poll and read

Key Differences

Common Pitfalls

Returning early without restoring the terminal

Using the deprecated frame.size()

Passing state to render_widget instead of render_stateful_widget

Blocking the loop with event::read() when you need to tick

Forgetting the KeyEventKind::Press filter on Windows

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A counter app

Exercise 2: A chat-style input box

Exercise 3: Test a render function headlessly

`ratatui::init()` and `ratatui::restore()`

Widgets, `Block`, and layout

Event handling with `poll` and `read`

Using the deprecated `frame.size()`

Passing state to `render_widget` instead of `render_stateful_widget`

Blocking the loop with `event::read()` when you need to tick

Forgetting the `KeyEventKind::Press` filter on Windows