SuperLightTUI

Superfast to write. Superlight to run.

Crate · Docs · Examples · Contributing

Showcase

Getting Started

cargo add superlighttui

fn main() -> std::io::Result<()> {
    slt::run(|ui: &mut slt::Context| {
        ui.text("hello, world");
    })
}

5 lines. No App struct. No Model/Update/View. No event loop. Ctrl+C just works.

A Real App

use slt::{Border, Color, Context, KeyCode};

fn main() -> std::io::Result<()> {
    let mut count: i32 = 0;

    slt::run(|ui: &mut Context| {
        if ui.key('q') { ui.quit(); }
        if ui.key('k') || ui.key_code(KeyCode::Up) { count += 1; }
        if ui.key('j') || ui.key_code(KeyCode::Down) { count -= 1; }

        ui.bordered(Border::Rounded).title("Counter").pad(1).gap(1).col(|ui| {
            ui.text("Counter").bold().fg(Color::Cyan);
            ui.row(|ui| {
                ui.text("Count:");
                let c = if count >= 0 { Color::Green } else { Color::Red };
                ui.text(format!("{count}")).bold().fg(c);
            });
            ui.text("k +1 / j -1 / q quit").dim();
        });
    })
}

State lives in your closure. Layout is row() and col(). Styling chains. That's it.

Why SLT

Your closure IS the app — No framework state. No message passing. No trait implementations. You write a function, SLT calls it every frame.

Everything auto-wires — Focus cycles with Tab. Scroll works with mouse wheel. Containers report clicks and hovers. Widgets consume their own events.

Layout like CSS, syntax like Tailwind — Flexbox with row(), col(), grow(), gap(), spacer(). Tailwind shorthand: .p(), .px(), .py(), .m(), .mx(), .my(), .w(), .h(), .min_w(), .max_w().

ui.container()
    .border(Border::Rounded)
    .p(2).mx(1).grow(1).max_w(60)
    .col(|ui| {
        ui.row(|ui| {
            ui.text("left");
            ui.spacer();
            ui.text("right");
        });
    });

Two core dependencies — crossterm for terminal I/O. unicode-width for character measurement. Optional: tokio for async, serde for serialization.

Widgets

18 built-in widgets, zero boilerplate:

ui.text_input(&mut name);                    // single-line input
ui.textarea(&mut notes, 5);                  // multi-line editor
if ui.button("Submit") { /* clicked */ }     // button returns bool
ui.checkbox("Dark mode", &mut dark);         // toggle checkbox
ui.toggle("Notifications", &mut on);         // on/off switch
ui.tabs(&mut tabs);                          // tab navigation
ui.list(&mut items);                         // selectable list
ui.table(&mut data);                         // data table
ui.spinner(&spin);                           // loading animation
ui.progress(0.75);                           // progress bar
ui.scrollable(&mut scroll).col(|ui| { });    // scroll container
ui.toast(&mut toasts);                       // notifications
ui.separator();                              // horizontal line
ui.help(&[("q", "quit"), ("Tab", "focus")]); // key hints
ui.bar_chart(&data, 24);                     // horizontal bars
ui.sparkline(&values, 16);                   // trend line ▁▂▃▅▇
ui.line_chart(&data, 40, 10);                // braille line chart
ui.canvas(40, 10, |cv| { cv.circle(20, 20, 15); }); // braille canvas

Every widget handles its own keyboard events, focus state, and mouse interaction.

Custom Widgets

Implement the Widget trait to build your own:

use slt::{Context, Widget, Color, Style};

struct Rating { value: u8, max: u8 }

impl Widget for Rating {
    type Response = bool;

    fn ui(&mut self, ui: &mut Context) -> bool {
        let focused = ui.register_focusable();
        let mut changed = false;

        if focused {
            if ui.key('+') && self.value < self.max { self.value += 1; changed = true; }
            if ui.key('-') && self.value > 0 { self.value -= 1; changed = true; }
        }

        let stars: String = (0..self.max)
            .map(|i| if i < self.value { '★' } else { '☆' })
            .collect();
        let color = if focused { Color::Yellow } else { Color::White };
        ui.styled(stars, Style::new().fg(color));
        changed
    }
}

// Usage: ui.widget(&mut rating);

Focus, events, theming, layout — all accessible through Context. One trait, one method.

Features

ui.text("styled").bold().italic().underline().fg(Color::Cyan).bg(Color::Black);

16 named colors · 256-color palette · 24-bit RGB · 6 modifiers · 4 border styles

slt::run_with(RunConfig { theme: Theme::light(), ..Default::default() }, |ui| {
    ui.set_theme(Theme::dark()); // switch at runtime
});

Dark and light presets. Custom themes with 13 color slots. All widgets inherit automatically.

• Double-buffer diff — only changed cells hit the terminal
• u32 coordinates — no overflow on large terminals
• Clipping — content outside container bounds is hidden
• Viewport culling — off-screen widgets are skipped entirely
• FPS cap — RunConfig { max_fps: Some(60), .. } for CPU control
• Non-TTY safety — graceful exit when stdout is not a terminal
• Resize handling — automatic reflow on terminal resize

let mut tween = Tween::new(0.0, 100.0, 60).easing(ease_out_bounce);
let value = tween.value(ui.tick());

let mut spring = Spring::new(0.0, 180.0, 12.0);
spring.set_target(100.0);

Tween with 9 easing functions. Spring with configurable stiffness and damping.

slt::run_inline(3, |ui| {
    ui.text("Renders below your prompt.");
    ui.text("No alternate screen.").dim();
});

Render a fixed-height UI below the cursor without taking over the terminal.

let tx = slt::run_async(|ui, messages: &mut Vec<String>| {
    for msg in messages.drain(..) { ui.text(msg); }
})?;
tx.send("Hello from background!".into()).await?;

Optional tokio integration. Enable with cargo add superlighttui --features async.

ui.error_boundary(|ui| {
    ui.text("If this panics, the app keeps running.");
});

ui.error_boundary_with(
    |ui| { /* risky code */ },
    |ui, msg| { ui.text(format!("Recovered: {msg}")); },
);

Catch widget panics without crashing the app. Partial commands are rolled back and a fallback is rendered.

cargo add superlighttui --features serde

Serialize/deserialize Style, Color, Theme, Border, Padding, Margin, Constraints, and Modifiers.

use slt::{TestBackend, EventBuilder, KeyCode};

let mut backend = TestBackend::new(80, 24);
let events = EventBuilder::new().key('q').key_code(KeyCode::Enter).build();
backend.run_with_events(events, |ui| {
    ui.text("test content");
});
assert!(backend.to_string().contains("test content"));

Headless rendering with TestBackend and event simulation with EventBuilder for automated testing.

Press F12 in any SLT app to toggle the layout debugger overlay. Shows container bounds, nesting depth, and layout structure.

Examples

Architecture

Closure → Context collects Commands → build_tree() → flexbox layout → diff buffer → flush

Each frame: your closure runs, SLT collects what you described, computes flexbox layout, diffs against the previous frame, and flushes only the changed cells.

~6,800 lines of Rust. 12 source files. No macros, no code generation, no build scripts.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT