 Widget Demo cargo run --example demo |
 Dashboard cargo run --example demo_dashboard |
 Website Layout cargo run --example demo_website |
 Spreadsheet cargo run --example demo_spreadsheet |
 Games cargo run --example demo_game |
 DOOM Fire Effect cargo run --release --example demo_fire |
cargo add superlighttuifn 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.
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.
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.
30+ 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.select(&mut sel); // dropdown select
ui.radio(&mut radio); // radio button group
ui.multi_select(&mut multi); // multi-select checkboxes
ui.tree(&mut tree); // expandable tree view
ui.virtual_list(&mut list, 20, |ui, i| {}); // virtualized 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.link("Docs", "https://docs.rs/slt"); // clickable hyperlink (OSC 8)
ui.modal(|ui| { ui.text("overlay"); }); // modal with dim backdrop
ui.overlay(|ui| { ui.text("floating"); }); // overlay without backdrop
ui.command_palette(&mut palette); // searchable command palette
ui.markdown("# Hello **world**"); // markdown rendering
ui.form_field(&mut field); // labeled input with validation
ui.chart(|c| { c.line(&data); c.grid(true); }, 50, 16); // line/scatter/bar chart
ui.scatter(&points, 50, 16); // standalone scatter plot
ui.histogram(&values, 40, 12); // auto-binned histogram
ui.bar_chart(&data, 24); // horizontal bars
ui.sparkline(&values, 16); // trend line ▁▂▃▅▇
ui.canvas(40, 10, |cv| { cv.circle(20, 20, 15); }); // braille canvas
ui.grid(3, |ui| { /* 3-column grid */ }); // grid layout
// v0.9 additions
ui.divider_text("Section Title"); // labeled horizontal divider
ui.alert("Saved!", AlertLevel::Success); // inline alert banner
ui.breadcrumb(&["Home", "Settings", "Profile"]); // navigation breadcrumb
ui.accordion(&mut acc, "Details", |ui| { }); // collapsible section
ui.badge("New", Color::Green); // inline status badge
ui.key_hint('q', "quit"); // single key hint chip
ui.stat("Users", "1,234", Trend::Up(12.0)); // metric with trend indicator
ui.definition_list(&[("CPU", "4 cores"), ("RAM", "16 GB")]); // term/value pairs
ui.empty_state("No results", "Try a different search"); // empty placeholder
ui.code_block("fn main() {}", "rust"); // syntax-highlighted codeEvery widget handles its own keyboard events, focus state, and mouse interaction.
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.
Layout
| Feature | API |
|---|---|
| Vertical stack | ui.col(|ui| { }) |
| Horizontal stack | ui.row(|ui| { }) |
| Grid layout | ui.grid(3, |ui| { }) |
| Gap between children | .gap(1) |
| Flex grow | .grow(1) |
| Push to end | ui.spacer() |
| Alignment | .align(Align::Center) |
| Padding | .p(1), .px(2), .py(1) |
| Margin | .m(1), .mx(2), .my(1) |
| Fixed size | .w(20), .h(10) |
| Constraints | .min_w(10), .max_w(60) |
| Percentage sizing | .w_pct(50), .h_pct(80) |
| Justify | .space_between(), .space_around(), .space_evenly() |
| Text wrapping | ui.text_wrap("long text...") |
| Borders with titles | .border(Border::Rounded).title("Panel") |
| Per-side borders | .border_top(false), .border_sides(BorderSides::horizontal()) |
| Responsive gap | .gap_at(Breakpoint::Md, 2) |
Styling
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
Theming
// 7 built-in presets
slt::run_with(RunConfig { theme: Theme::catppuccin(), ..Default::default() }, |ui| {
ui.set_theme(Theme::dark()); // switch at runtime
});
// Build custom themes — unfilled fields default to Theme::dark()
let theme = Theme::builder()
.primary(Color::Rgb(255, 107, 107))
.accent(Color::Cyan)
.build();7 presets (dark, light, dracula, catppuccin, nord, solarized, tokyo_night). Custom themes with 15 color slots. All widgets inherit automatically.
Style Recipes
use slt::{ContainerStyle, Border, Color};
// Define reusable styles — const for zero runtime cost
const CARD: ContainerStyle = ContainerStyle::new()
.border(Border::Rounded).p(1).bg(Color::Indexed(236));
const DANGER: ContainerStyle = ContainerStyle::new()
.bg(Color::Red);
// Apply one
ui.container().apply(&CARD).col(|ui| { ... });
// Compose multiple — last write wins
ui.container().apply(&CARD).apply(&DANGER).col(|ui| { ... });
// Mix with inline overrides
ui.container().apply(&CARD).grow(1).gap(2).col(|ui| { ... });Define once, apply anywhere. const styles have zero runtime cost. Compose by chaining .apply() calls — inline methods always override.
Dark Mode
ui.container()
.bg(Color::White)
.dark_bg(Color::Rgb(30, 30, 46)) // applied when dark mode active
.col(|ui| { ... });
ui.set_dark_mode(false); // toggleContainer-level style overrides that activate based on dark/light mode.
Responsive Layout
ui.container()
.w(20).md_w(40).lg_w(60) // width changes at breakpoints
.p(1).lg_p(2)
.col(|ui| { ... });35 breakpoint-conditional methods (xs_, sm_, md_, lg_, xl_ × w, h, min_w, max_w, gap, p, grow). Breakpoints: Xs (<40), Sm (40–79), Md (80–119), Lg (120–159), Xl (≥160).
Group Hover
ui.group("card")
.border(Border::Rounded)
.group_hover_bg(Color::Indexed(238))
.col(|ui| {
ui.text("Hover anywhere on card to highlight");
});Parent container hover/focus state propagates to children. Like Tailwind's group-hover:.
Hooks
let count = ui.use_state(|| 0i32);
ui.text(format!("{}", count.get(ui)));
if ui.button("+1") { *count.get_mut(ui) += 1; }
let doubled = *ui.use_memo(&count_val, |c| c * 2);React-style persistent state in immediate mode. State<T> handle pattern. Call in same order every frame.
Rendering
- Double-buffer diff — only changed cells hit the terminal
- Synchronized output — DECSET 2026 prevents tearing on supported terminals
- 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
collect_all()— single DFS pass replaces 7 separate tree traversals (v0.9)- Delta flush —
apply_style_delta()emits only changed attributes per cell (v0.9) - Keyframes pre-sort — stops sorted at build time, not per-frame (v0.9)
Animation
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);
let mut kf = Keyframes::new(120)
.stop(0.0, 0.0).stop(0.5, 100.0).stop(1.0, 50.0)
.loop_mode(LoopMode::PingPong);
let mut seq = Sequence::new()
.then(0.0, 50.0, 30, ease_out_quad)
.then(50.0, 100.0, 30, ease_in_out_cubic);
let mut stagger = Stagger::new(0.0, 1.0, 40).delay(8);
let val = stagger.value(tick, item_index);Tween with 9 easing functions. Spring physics. Keyframe timelines with loop modes. Sequence chains. Stagger for list animations. All support .on_complete() callbacks (.on_settle() for Spring).
Inline Mode
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.
Async
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.
Error Boundary
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.
Input Validation
let mut email = TextInputState::with_placeholder("you@example.com");
ui.text_input(&mut email);
email.validate(|v| {
if v.contains('@') { Ok(()) } else { Err("Invalid email".into()) }
});Call .validate() after text_input() to show inline error messages. Works with form_field() for grouped form validation.
Modal & Overlay
ui.modal(|ui| {
ui.bordered(Border::Rounded).pad(2).col(|ui| {
ui.text("Confirm?").bold();
if ui.button("OK") { show = false; }
});
});
ui.overlay(|ui| {
ui.row(|ui| {
ui.spacer();
ui.text("Status: Online").fg(Color::Green);
});
});modal() dims the background and renders content on top. overlay() renders floating content without dimming. Both support full layout and interaction.
Hyperlinks
ui.link("Documentation", "https://docs.rs/superlighttui");Renders clickable OSC 8 hyperlinks. Ctrl/Cmd+click opens in browser on supporting terminals (iTerm2, WezTerm, Ghostty, Windows Terminal).
Snapshot Testing
use slt::TestBackend;
let mut backend = TestBackend::new(40, 10);
backend.run(|ui| {
ui.bordered(Border::Rounded).pad(1).col(|ui| {
ui.text("Hello");
});
});
insta::assert_snapshot!(backend.to_string_trimmed());Use with insta for snapshot-based UI regression tests.
Serde
cargo add superlighttui --features serdeSerialize/deserialize Style, Color, Theme, Border, Padding, Margin, Constraints, and Modifiers.
Testing
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.
Direct Buffer Access
ui.container().w(40).h(20).draw(|buf, rect| {
for y in rect.y..rect.bottom() {
for x in rect.x..rect.right() {
buf.set_char(x, y, '█', Style::new().fg(Color::Rgb(x as u8, 0, y as u8)));
}
}
});ContainerBuilder::draw() gives you raw access to the cell buffer for pixel-level rendering. Useful for custom effects, games, and image rendering. The closure receives (&mut Buffer, Rect) and runs after layout is resolved.
Syntax-Highlighted Code
ui.code_block("fn greet(name: &str) -> String {\n format!(\"Hello, {name}!\")\n}", "rust");Renders code with One Dark palette syntax highlighting. Supports Rust keywords, string literals, comments, and numeric literals. Falls back to plain monospace for unknown languages.
Debug
Press F12 in any SLT app to toggle the layout debugger overlay. Shows container bounds, nesting depth, and layout structure.
| Example | Command | What it shows |
|---|---|---|
| hello | cargo run --example hello |
Minimal setup |
| counter | cargo run --example counter |
State + keyboard |
| demo | cargo run --example demo |
All widgets |
| demo_dashboard | cargo run --example demo_dashboard |
Live dashboard |
| demo_cli | cargo run --example demo_cli |
CLI tool layout |
| demo_spreadsheet | cargo run --example demo_spreadsheet |
Data grid |
| demo_website | cargo run --example demo_website |
Website in terminal |
| demo_game | cargo run --example demo_game |
Tetris + Snake + Minesweeper |
| demo_fire | cargo run --release --example demo_fire |
DOOM fire effect (half-block) |
| demo_ime | cargo run --example demo_ime |
Korean/CJK IME input |
| inline | cargo run --example inline |
Inline mode |
| anim | cargo run --example anim |
Tween + Spring + Keyframes |
| demo_v050 | cargo run --example demo_v050 |
v0.5.0 features |
| demo_infoviz | cargo run --example demo_infoviz |
Data visualization |
| async_demo | cargo run --example async_demo --features async |
Background tasks |
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.
Pure Rust. No macros, no code generation, no build scripts.
See CONTRIBUTING.md for guidelines.