Porting a ratatui app¶

This page is for people with a ratatui app who want to move it to intuiTUIve. You do not have to move all of it at once:

Paths 2 and 3 are the same work done at different speeds, so the recipe below covers both. Three complete ports show where it leads:

• An ops dashboard, written both ways in tests/versus_ratatui.rs: the ratatui version and the intuiTUIve one draw the same screen, and CI measures them against each other.
• A Yazi-style file manager. Yazi is the most-starred app built on ratatui. It is rebuilt on intuiTUIve in examples/files.rs (cargo run -p rs-rich-intuituive --features files --example files), on the files plugin's Miller columns, with Yazi's layout, theme, status line and default keymap (chords and their which-key pop-up included), previews by type loaded in the background, selection and visual mode, yank and paste, trash and delete as background tasks, create and rename, find, filter, sorting, git signs, archives, a fuzzy finder, tabs and the help. See the walkthrough below.
• An oscilloscope. scope-tui draws audio as an oscilloscope, a vectorscope and a spectroscope, twenty or more times a second. It is rebuilt in examples/scope.rs (cargo run -p rs-rich-intuituive --example scope --features pcm), with its keys, options, trigger, averaging, Braille plots and live capture (with the audio feature). See the walkthrough below.

What changes, in one table¶

Path 1: rich inside ratatui¶

Nothing about your app changes. rs-rich-ratatui makes any rich renderable a ratatui Widget:

frame.render_widget(&RichWidget::new(&table), area);
frame.render_widget(RichWidget::markup("[b]q[/] quit"), footer);

See Using rich with ratatui.

Path 2: ratatui widgets inside intuiTUIve¶

rs-rich-ratatui's RatatuiComponent (its interact feature) runs a ratatui draw function as a component, and component(..) puts it in the tree. The widget can read signals: when they change, it draws again.

[dependencies]
rs-rich-intuituive = "0.0.5"
rs-rich-ratatui = { version = "0.0.1", features = ["interact"] }
ratatui = "0.30"

use intuituive::prelude::*;
use ratatui::widgets::{Block, Gauge, Widget};
use rich_ratatui::RatatuiComponent;

App::new(|| {
    let done = signal(1u16);
    // Your existing widget code, unchanged, reading a signal.
    let gauge = RatatuiComponent::<(), ()>::new(move |area, buf| {
        Gauge::default()
            .block(Block::bordered().title("Progress"))
            .percent(done.get() * 10)
            .render(area, buf);
    });
    column([
        component(gauge, |_, _| {}).no_focus().fixed(3),
        text!("done {done}/10").auto(),
    ])
    .on_key("+", move |_| done.update(|d| *d += 1))
    .on_key("q", |cx| cx.quit())
})
.run()

This is tested in tests/ratatui_widgets.rs. From here, port one widget at a time, the busiest first: each port also moves that part of the screen from "redraw when anything changes" to "redraw when its own state changes".

Path 3: the recipe¶

1. State becomes signals¶

// ratatui
struct App {
    selected: usize,
    tick: u64,
    log: Vec<String>,
}

// intuiTUIve, inside App::new(|| { … })
let selected = signal(0usize);
let tick = signal(0u64);
let log = Log::new(500);

Signals are Copy: move them into every closure that needs them, with no Rc<RefCell<..>>. Derived values become memos: let left = memo(move || todos.with(|t| t.iter().filter(|t| !t.done).count())). In handlers, read with get(); to read without subscribing anything (rarely needed), use get_untracked().

2. The draw function becomes a tree¶

A ratatui draw runs every frame and lays out from scratch. In intuiTUIve you build the same shape once:

// ratatui
let [header, body, footer] = Layout::vertical([
    Constraint::Length(1),
    Constraint::Min(0),
    Constraint::Length(1),
])
.areas(frame.area());
let [left, right] =
    Layout::horizontal([Constraint::Percentage(40), Constraint::Percentage(60)]).areas(body);

// intuiTUIve
column([
    header.fixed(1),
    row([services.percent(40), detail_and_log.percent(60)]),
    footer.fixed(1),
])

Each closure inside the tree (text!, text(..), renderable(..), list's items) re-runs only when the signals it read change. You no longer pass Rects around; when you need one (for a click), the framework keeps it.

3. Widgets become nodes¶

Most widgets have a direct counterpart (see the table above). Three are worth a closer look:

• Lists. list(items, selected) is List and ListState together. It keeps the selection in view, highlights it in the theme's selected style and binds ↑/↓, j/k, Home/End and PageUp/PageDown while it has the focus. Bind Enter yourself.
• Tables. table(columns, rows, selected) is Table and TableState together: sized columns, a header that stays, the keys and clicks. TableOptions sorts, scrolls across and adds a cell cursor, and its options can follow signals; .cursor_by(|i| key) keeps the selection on its row through a re-sort. A file too big to hold is a TableSource behind view_of, filtered and sorted on a worker thread. See Tables and scrolling.
• Popups. Replace Clear plus a centred Rect with cx.modal(Size::Auto, Size::Auto, build). Keys go to the modal until cx.pop().

Styles move from Style::new().fg(..) to markup ("[bold red]…[/]") or, better, theme names ("[bad]…[/]") that a theme file can change while the app runs. rs-rich-ratatui's to_rich_style converts an existing ratatui Style.

4. The event loop becomes bindings¶

// ratatui
match event::read()? {
    Event::Key(key) => match key.code {
        KeyCode::Up | KeyCode::Char('k') => app.selected = app.selected.saturating_sub(1),
        KeyCode::Char('q') => return Ok(()),
        _ => {}
    },
    _ => {}
}

// intuiTUIve
list(items, selected)                 // ↑/k and ↓/j are built in
    .on_key("enter", move |cx| open(selected.get(), cx));
root.on_key("q", |cx| cx.quit());

Keys go to the focused node first and bubble up to its ancestors, so a key bound on the root works anywhere unless something deeper uses it. Replace a hand-written Focus enum with .focusable() nodes: Tab and Shift+Tab move between them, panels highlight while the focus is inside, and .focus_style("reverse") marks a focused row.

5. Ticks, threads and side effects¶

watch is the one most ports need: it replaces the "compare with last frame's value" checks a ratatui loop accumulates.

6. Tests¶

TestBackend asserts become scripts, which press keys, type text, click, resize and wait on a virtual clock:

let rows = app.render_with(&["j", "j", "enter", "q"], 80, 24)?;
assert!(rows[3].contains("selected"));

For more control, App::run_on with intuituive::interact::headless::Headless records every frame and every byte sent. App::wait_for_tasks(true) makes background work finish before the next scripted key, so tests of loading states are deterministic.

7. Check the result¶

Run the port with INTUITUIVE_INSPECT=1. The inspector shows which nodes drew in each frame. A key press should redraw what it changed and nothing else. If a whole panel redraws on every tick, a closure inside it reads a signal it does not need: the inspector's trace (Shift+F12, then 4) names each signal written and the nodes it made dirty, and its timings (3) show which nodes take the time.

Path 4: keep your loop¶

A ratatui program can keep its terminal, its loop and its frame, and give part of the screen to an intuiTUIve app. App::driver(width, height) runs the app without a loop of its own. Each turn, call:

• update(elapsed);
• render(), then copy driver.screen().lines() into your buffer with rs-rich-ratatui's lines_to_buffer;
• event(…) with the app's events, translated by rich_interact::event::from_crossterm.

examples/in_ratatui.rs is the whole program, and the guide's Owning the loop has the details. This is the way in for an app too big to port at once: move one pane at a time.

Worked example: a Yazi-style file manager¶

examples/files.rs reproduces Yazi as it looks and behaves out of the box: its 1:4:3 columns, its default dark theme, icons and type colours, header, tab strip and status line, and its default keymap. It is built only from the framework's ready-made components: the core's bars, help, fuzzy lists and dialogs, and the files plugin's Miller columns, previews, tabs, selection, yank, openers, tasks, finder, frecency, search, shell, bulk rename and spotter. What it writes itself is Yazi's keymap and what each key does (about 1,200 lines, down from round 3's 1,450). Its tests are in tests/files.rs. It does not reuse any of Yazi's code: it is a rebuild of the behaviour, showing how a large ratatui app's ideas map.

cargo run -p rs-rich-intuituive --features files --example files
cargo run -p rs-rich-intuituive --features files,archive,watch,art --example files

Where it differs from Yazi, and why:

• Opening: $EDITOR (split on spaces) and the system opener cover Yazi's edit, open, play and reveal, and extract with the archive feature.
• Images are drawn in half blocks: the image node places no Kitty or Sixel graphics yet.
• The selection and visual mode are one for all tabs (Yazi keeps them per tab); switching tabs ends visual mode.
• h in a search's listing goes up from the directory searched, where Yazi goes back to it.
• The help filters as you type, where Yazi's moves with j/k and filters after /.
• Icons are off unless --icons is given or RICH_NERD_FONT=1 says a Nerd Font is in use: an installed Nerd Font may not be the terminal's.

Two things the port shows:

1. Slow work belongs on a worker, including rendering. Highlighting a language for the first time compiles its grammar, which takes seconds in a debug build for Markdown and its embedded languages. The app warms the likely grammars at start-up, and the preview worker highlights the text at the pane's size, so the app's thread only copies the finished lines onto the screen. Yazi does this for the same reason.
2. The components are signals, so they compose by watching. Miller's columns know nothing of tabs or selections; files::tabs and files::selection watch m.cwd to keep each tab's history and drop a visual range, and the app reads m.hovered, m.cursor and m.current for its status line, as Yazi's Lua components read its cx.

Worked example: scope-tui, an oscilloscope¶

examples/scope.rs rebuilds scope-tui in about 1,300 lines, built only from intuiTUIve's components and rs-rich-ext's. Its tests are in tests/scope.rs. Like the file manager, it reuses none of the original's code. Where the file manager redraws when you press a key, this app redraws whenever a new buffer of audio arrives.

The test signal is made of dsp::partials, tone, noise(..).low_pass(..) and mix, and ? opens the framework's help, each scope's keys in a section of its own (.bind_in("oscilloscope", …)).

What the port shows:

1. Redraw follows what changed. The plot reads the frame, so it draws once per buffer. Each header cell reads only its own value. The fps cell draws once a second, and the other cells draw only when a key changes them. While the scope is paused nothing draws at all, and identical buffers (the --still test signal) draw nothing either.
2. Take the newest frame from a stream rather than queueing them. latest, latest_every and a capture's samples() keep only the newest buffer, so when the terminal falls behind the app skips old buffers rather than drawing a backlog. on_write sees every write, so two buffers of silence count as two frames, as in scope-tui.
3. Threads can keep to the app's clock. Under wait_for_tasks(true) the test signal and a file's beat run on the app's clock, so the tests count frames exactly.
4. Ported layouts can keep ratatui's arithmetic. cells places the header's cells in the same columns as scope-tui's table at every width, and cuts them as a table cell is cut.

It differs from scope-tui in a few deliberate ways:

• audio and pulse need the crate's audio feature (and ALSA's headers on Linux); without it they say so and point at file -. With audio alone, pulse opens ALSA's pulse device (PulseAudio's default source); the pulse feature reaches every PulseAudio and PipeWire source.
• Its file source reads a whole buffer per channel. scope-tui 0.3.5's reads half of one, so its waveform fills half the width and its spectroscope stops at the first frame; this one draws what scope-tui's audio sources do. Past the end of a file it draws silence a buffer period apart, where scope-tui reads silence as fast as it can.
• --tune takes equal-temperament pitches (dsp::note_hz), where scope-tui doubles a table of octave-0 pitches rounded to the hundredth: about one note in ten gives a buffer a sample longer or shorter (E2 is 582 samples at 48 kHz here, 583 in scope-tui).
• The trigger threshold keeps scope-tui's 16-bit units, and compares them with the samples scaled back up, so it triggers on every source.
• Where the vectorscope's reference lines cross with nothing drawn over them, the two grid lines merge in one cell; scope-tui draws its second reference over the first.
• ? lists the keys, and options may follow the source.
• For now it shows at most 20 frames a second (23 is scope-tui's at its default buffer): the framework picks up values from other threads every 50 ms, a bug listed in the demo gaps.

Credit for ports¶

Every app ported into this repository names where it came from, who made it and its licence: in the example's header comment, in its section of this guide, and in the recordings gallery. A port that copies code from the original must also keep the original's copyright and licence notice with that code, as MIT and Apache-2.0 require. The ports here reuse none, so the credit is all they carry. Port your own app the same way.

The ports so far, and whose they are:

• Yazi, by sxyazi and its contributors, MIT licence: files.
• scope-tui, by alemi, MIT licence: scope.
• ratatui's example apps, by Florian Dehau and the Ratatui Developers, MIT licence: rebuilt from ratatui 0.30, with sample data of our own, and listed in ratatui's examples, rebuilt.

Common questions¶

Where did my Frame go? There is none. Nodes draw themselves into the rectangle the layout gives them. A leaf(|console, width, height| …) returning rich segments is the closest thing to a custom Widget::render.

Can I keep my ratatui backend? App::run uses rs-rich-interact's terminal session (crossterm). To keep your own terminal and loop, ratatui's included, drive the app with App::driver (path 4). App::run_with drives it with termion or termwiz instead, behind this crate's features of those names (see Backends).

Do I lose performance? Not where most frames change little: the benchmark has intuiTUIve ahead on a status tick, a selection move and a log append, because it redraws and sends only what changed. Where every cell changes each frame (a full-screen swatch, a chart redrawn whole) it is ahead too when it draws through rs-rich-ext's fast path (Canvas::put_rgb, Canvas::draw, drawn), as the same page shows; a renderable drawn as rich segments takes longer. For a log or a list that scrolls, try App::paint_strategy(PaintStrategy::Best) (see paint strategies).

What about async runtimes? Keep yours. Send results to the app with a Proxy, or use spawn_future for futures that do not need a particular runtime.