Install

pito-list is a library for ratatui apps. It isn’t on crates.io: add it from git, pinned to a release tag. The same line works on Linux, Windows and macOS.

Add the dependency

cargo add pito-list --git https://github.com/gmrdad82/pito-list --tag v1.0.1

or in Cargo.toml:

[dependencies]
pito-list = { git = "https://github.com/gmrdad82/pito-list", tag = "v1.0.1" }

The crate is edition 2024, so it needs Rust 1.85 or newer, and it draws with ratatui 0.30. Its own dependencies are ratatui (with no backend feature), unicode-width and unicode-segmentation.

The crossterm feature

Turn it on to convert crossterm’s key events into the list’s keys with Key::from(event):

cargo add pito-list --git https://github.com/gmrdad82/pito-list --tag v1.0.1 --features crossterm

pito-list = { git = "https://github.com/gmrdad82/pito-list", tag = "v1.0.1", features = ["crossterm"] }

It brings in crossterm 0.29 with its events feature only. Without it the crate has no backend dependency, and an app on another backend builds the Key values itself.

Quick start

Three rows, three columns, the cursor moved down once, drawn into a ratatui buffer at two widths:

use pito_list::{Cell, Column, Key, List, ListView, Row, Styles};
use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::{Color, Modifier, Style},
    widgets::Widget,
};

let columns = [
    Column::new("Job", 8, 14).pinned(),
    Column::new("Owner", 5, 7).priority(1),
    Column::new("Message", 8, 0),
];
let mut list = List::new().with_rows([
    Row::new(["deploy api", "web", "uploading the bundle"]),
    Row::new([
        Cell::new("build docs"),
        Cell::new("docs"),
        Cell::new("waiting for a runner").faint(),
    ]),
    Row::new(["rotate logs", "ops", "starts at 02:00"]),
]);
list.key(Key::Down);

let styles = Styles::new().selected(Style::new().fg(Color::Yellow).add_modifier(Modifier::BOLD));
for width in [44, 24] {
    let area = Rect::new(0, 0, width, 4);
    let mut buffer = Buffer::empty(area);
    ListView::new(&mut list, &columns)
        .styles(styles)
        .header(true)
        .render(area, &mut buffer);
}

It draws, at 44 and then 24 cells wide (the Owner column drops when it doesn’t fit):

  Job             Owner    Message
  deploy api      web      uploading the bu…
▌ build docs      docs     waiting for a ru…
  rotate logs     ops      starts at 02:00

  Job           Message
  deploy api    uploadi…
▌ build docs    waiting…
  rotate logs   starts …

Draw a list in your app puts a list in a real terminal app, with its keys.

Run the demo

The demo is a small terminal app over sample jobs, the one recorded in the clips on these pages:

git clone https://github.com/gmrdad82/pito-list
cd pito-list
cargo run --example demo --features crossterm

Move with the arrows or j and k, press v for a range, ctrl+d and ctrl+u to page, g and G for the ends, enter to open, and ctrl+c twice to quit.