Ratagrid

An independent, typed data grid for Ratatui: sorting, selection, search, column resizing and pagination.

Documentation and demo · crates.io · API reference · Usage guide

The demo shows real terminal I/O rendered into media, using synthetic records.

Run it

Rust 1.99.0 is required.

git clone https://github.com/kahwee/ratagrid.git
cd ratagrid
cargo run --release --locked --example playground

Enable optional full-value panels for truncated cells:

cargo run --release --locked --example playground -- --cell-details

Shrink Workload, then hover a data cell for 500 ms or click it and press Enter. Escape closes the panel; Up/Down, PageUp/PageDown and Home/End scroll a keyboard-opened panel. The mouse wheel over the panel also scrolls it. This option is disabled by default. Library configuration.

In 0.3.0, a column can render a horizontal bar with .bar_chart(max, value). Try cargo run --locked --example bar_chart for synthetic disk usage with colored bars and a separate size column. See bar chart columns.

Use with Ratatui

ratagrid = "0.3"
ratatui = "0.30"
crossterm = "0.29"

Start with the example guide to choose an integration or demo.

A complete keyboard example (cargo run --locked --example quickstart):

use crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};
use ratagrid::{Column, Grid};

fn main() -> std::io::Result<()> {
    let mut grid = Grid::new(
        vec![Column::new("Value", 12, |n: &i64| n.to_string()).sortable(|a, b| a.cmp(b))],
        vec![20, -3, 100],
    );
    let mut terminal = ratatui::init();
    let result = (|| {
        loop {
            terminal.draw(|frame| frame.render_widget(grid.widget(), frame.area()))?;
            let input = event::read()?;
            if matches!(&input, Event::Key(k) if k.code == KeyCode::Char('q')
                && k.kind != KeyEventKind::Release
                && !k.modifiers.intersects(KeyModifiers::CONTROL | KeyModifiers::ALT | KeyModifiers::SUPER)
                && !grid.is_searching())
            {
                break;
            }
            grid.handle_event(&input);
        }
        Ok(())
    })();
    ratatui::restore();
    result
}

Use arrows to select, Tab + Enter to sort, / to search, and q to quit. For mouse capture and synthetic financial amounts, see positions.rs. Your application owns the terminal, focus and data source.

For a SQLite adapter with global search, one-based application pages, optional sorting and changing totals, run cargo run --locked --example database; see the adapter guide.

For native database cursor/keyset pagination, use Grid::new_cursor_paged, handle Action::CursorPageRequested, and return rows plus the next token. Try cargo run --locked --example cursor; see the cursor integration guide.

Feature guide · Pagination · Release notes and migration · Contributing · MIT license

GitHub benchmarks

Benchmarks run across Linux, macOS and Windows when a PR opens ready for review, when a draft becomes ready, weekly on Mondays at 09:17 UTC, or manually. They do not run on ordinary pushes or subsequent PR commits. Correctness CI still checks all three platforms on every push and PR update.

Measured 2026-10-05 on GitHub-hosted runners at 94312da. Workflow and logs · Raw CSV/JSON.

Release-mode, in-memory runtime medians from three process runs; terminal I/O and real database/network work excluded. Build timings cover Clippy, tests, doctests and rustdoc with pre-fetched dependencies; setup and release compilation excluded. Fresh/warm build figures are medians of two runs each. Compare within a platform; hosted hardware/load varies.

• ubuntu-24.04: Compared with same-runner baseline 6ca93d7. 0 possible runtime regression(s).
• macos-15: Compared with same-runner baseline 6ca93d7. 0 possible runtime regression(s).
• windows-2025: Compared with same-runner baseline 6ca93d7. 0 possible runtime regression(s).

Same-runner comparison on ubuntu-24.04 against 6ca93d7:

• render_selected: 0.302 → 0.136 ms (-55.1%).
• sorted_50_small_updates_and_render: 15.021 → 7.155 ms (-52.4%).
• sorted_50_cross_dataset_and_render: 23.423 → 19.779 ms (-15.6%).

Same-runner comparison on macos-15 against 6ca93d7:

• render_selected: 0.249 → 0.101 ms (-59.3%).
• sorted_50_small_updates_and_render: 22.088 → 5.863 ms (-73.5%).
• sorted_50_cross_dataset_and_render: 26.776 → 19.580 ms (-26.9%).

Same-runner comparison on windows-2025 against 6ca93d7:

• render_selected: 0.364 → 0.168 ms (-54.0%).
• sorted_50_small_updates_and_render: 36.275 → 6.505 ms (-82.1%).
• sorted_50_cross_dataset_and_render: 28.173 → 28.100 ms (-0.3%).

Slowdown warnings require both >25% and >0.05 ms; paired runs use the same-runner reference, otherwise the frozen baseline. They are advisory. Method, triggers and baseline policy.