Crate ratada 

ratada: a reusable ratatui widget toolkit.

The toolkit owns the generic terminal, navigation, rendering and modal building blocks over ratatui/crossterm (plus unicode-width, nucleo-matcher, pulldown-cmark, chrono, log) and never depends on any application types. The theme layer supplies the framework-agnostic styling vocabulary (a theme::Palette and theme::Glyphs, bundled into a theme::Skin); the host supplies lifecycle hooks (see terminal::Tui::with_hooks). Theme colors are mapped to ratatui styles in style.

Diagnostics for degraded conditions (a missing clipboard tool, an unreadable directory, an invalid color override, a failed terminal restore on exit) are emitted through the log facade at warn/error; install a logger to surface them.

Example

Implement Screen and hand it to run, which owns the draw/input loop inside a raw-mode Tui guard:

use ratada::prelude::*;
use ratatui::{Frame, text::Line};
use crossterm::event::{KeyCode, KeyEvent};

struct App {
    count: u32,
}

impl Screen for App {
    type Error = std::io::Error;

    fn render(&self, frame: &mut Frame) {
        frame.render_widget(Line::from(format!("count: {}", self.count)), frame.area());
    }

    fn handle_key(&mut self, key: KeyEvent, _tui: &mut Tui) -> std::io::Result<Flow> {
        match key.code {
            KeyCode::Char('q') => Ok(Flow::Quit),
            KeyCode::Char(' ') => {
                self.count += 1;
                Ok(Flow::Continue)
            }
            _ => Ok(Flow::Continue),
        }
    }
}

let mut tui = Tui::new()?;
run(&mut tui, &mut App { count: 0 })?;

Re-exports

pub use driver::Flow;

pub use driver::Screen;

pub use driver::run;

pub use modal::ModalSignal;

pub use overlay::PopupFlow;

pub use overlay::popup;

pub use terminal::Tui;

pub use terminal::TuiEvent;

Modules

autocomplete

Inline autocomplete dropdown for text fields.

chrome

Shared chrome: the borderless view panels and the modal frame.

clipboard

Best-effort clipboard access via the platform’s command-line tools.

color_picker

A color picker modal: switchable RGB/HSL/OKLCH channels with gradient sliders, an editable hex field, palette presets and a live preview.

command_palette

Fuzzy command palette overlay: pick a command and run it.

date_picker

Calendar date picker modal.

date_range_picker

A calendar date-range picker modal: pick a start day, then an end day.

double_press

“Press twice within a second to confirm” detection.

driver

Generic event-loop driver: a Screen trait and the run loop.

editor

Launching an external editor ($EDITOR) on a piece of text via a temp file.

finder

A fuzzy picker modal: filter-as-you-type selection over arbitrary items.

form

A schema-driven form modal.

fuzzy

Fuzzy matching and match highlighting, built on nucleo-matcher.

gauge

A horizontal progress gauge: an accent bar with a centered percentage label.

header

A header bar with an accented brand and dim secondary text.

help

Scrollable, fuzzy-searchable help overlay listing key bindings in sections.

input

Shared text editing: one caret with an optional selection anchor over a String. This is the single source of editing behaviour for every text field, so shortcuts stay consistent.

layout

Layout helpers.

list

A selectable, vertically scrollable list with a scrollbar.

markdown

A small, self-contained Markdown renderer for ratatui.

modal

Reusable modal widgets. Each is a thin wrapper over overlay::popup: it sets up its state and closures and returns a ModalSignal. The dimmed backdrop, box centering and event loop live in overlay, not here.

month_picker

Month picker modal: a YYYY-MM header over a 3x4 Jan-Dec grid.

nav

Reusable list navigation and scroll-offset helpers.

opener

Opening a file in the operating system’s default application.

overlay

The single overlay primitive: a generic popup driver plus the dimming backdrop shared by every modal, picker and overlay.

pager

A read-only text pager modal: scroll long text with an incremental search.

path_picker

A filesystem path picker modal.

prelude

The common imports for building a TUI on ratada: the terminal guard, the event-loop driver and the shared box decoration. Glob-import it with use ratada::prelude::*;.

quit

The opt-in confirmation asked before an app quits.

scroll

Scrollbar rendering (vertical and horizontal).

shortcut_hints

Shortcut hints: wrapped (key, description) tokens, optionally grouped under aligned labels.

sidebar

A sidebar: a sectioned, keyboard-navigable menu column.

slider

A numeric slider/stepper modal: pick a value in a bounded range.

spinner

A small text spinner with Unicode (braille) and ASCII frames.

statusbar

A one-line status bar: left- and right-aligned segments over a subtle tint.

style

ratatui adapter for framework-agnostic crate::theme::Color values.

swatches

A multi-mode color picker modal: pick from named swatches, a hue/saturation grid, a grayscale ramp or the theme palette.

table

An interactive table: typed sorting, fuzzy filtering, row/cell multi-select, multi-line rows and data-driven styling.

tabs

A wrapping, segment-aware top tab bar: a brand plus numbered view tabs.

terminal

RAII terminal guard and event reader.

text

Text helpers for terminal rendering.

textarea

A multi-line text area: wrapped editing with a caret, selection and clipboard. Reuses TextCursor and the shared edit core input::apply_edit_key from the input module, so it carries the same shortcuts as a single-line field - including Ctrl+U/Ctrl+K, which act on the display line, not the logical one.

theme

Framework-agnostic theming: colors, palette, glyphs and themes.

theme_preview

A read-only preview of the active theme: every palette color as a labeled swatch, plus the accent variant ladder.

toast

Transient toast notifications: timed, stacked messages in semantic colors.

tree

A collapsible tree view: a hierarchical, keyboard-navigable list.