{"id":47110835,"url":"https://github.com/subinium/superlighttui","last_synced_at":"2026-05-30T11:00:37.580Z","repository":{"id":343954259,"uuid":"1179850291","full_name":"subinium/SuperLightTUI","owner":"subinium","description":"🦀 An immediate-mode Rust TUI framework with flexbox layout and Tailwind-style chaining API.","archived":false,"fork":false,"pushed_at":"2026-05-29T02:07:11.000Z","size":14924,"stargazers_count":155,"open_issues_count":37,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-29T02:09:54.483Z","etag":null,"topics":["cli","immediate-mode","rust","terminal","tui"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/superlighttui","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/subinium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-12T12:54:02.000Z","updated_at":"2026-05-27T10:18:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"ed023ea8-9958-47f5-9dff-bf0d6d77ee7a","html_url":"https://github.com/subinium/SuperLightTUI","commit_stats":null,"previous_names":["subinium/superlighttui"],"tags_count":71,"template":false,"template_full_name":null,"purl":"pkg:github/subinium/SuperLightTUI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subinium%2FSuperLightTUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subinium%2FSuperLightTUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subinium%2FSuperLightTUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subinium%2FSuperLightTUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/subinium","download_url":"https://codeload.github.com/subinium/SuperLightTUI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subinium%2FSuperLightTUI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33689564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","immediate-mode","rust","terminal","tui"],"created_at":"2026-03-12T17:41:03.793Z","updated_at":"2026-05-30T11:00:37.574Z","avatar_url":"https://github.com/subinium.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# SuperLightTUI\n\n**Superfast** to write. **Superlight** to run.\n\n[![Crate Badge]][Crate]\n[![Docs Badge]][Docs]\n[![CI Badge]][CI]\n[![MSRV Badge]][Crate]\n[![Downloads Badge]][Crate]\n[![License Badge]][License]\n\n[Docs Index] · [Quick Start] · [Widget Guide] · [Patterns Guide] · [Examples Guide] · [Backends Guide] · [Architecture Guide]\n\n**English** · [中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [日本語](docs/README.ja.md) · [한국어](docs/README.ko.md)\n\n\u003c/div\u003e\n\nSuperLightTUI is an immediate-mode TUI library for Rust with a deliberately small public grammar.\nYou write one closure, SLT calls it every frame, and the library handles layout, focus, diffing, and rendering.\n\nIt is designed for fast product iteration, approachable Rust syntax, and serious backend discipline.\nThat makes it work equally well for humans prototyping a tool and for coding agents generating UI from docs.\n\n## Showcase\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo.png\" alt=\"Widget Demo\" /\u003e\u003cbr/\u003e\u003cb\u003eWidget Demo\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo_dashboard.png\" alt=\"Dashboard\" /\u003e\u003cbr/\u003e\u003cb\u003eDashboard\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo_dashboard\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo_website.png\" alt=\"Website\" /\u003e\u003cbr/\u003e\u003cb\u003eWebsite Layout\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo_website\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo_spreadsheet.png\" alt=\"Spreadsheet\" /\u003e\u003cbr/\u003e\u003cb\u003eSpreadsheet\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo_spreadsheet\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo_game.gif\" alt=\"Games\" /\u003e\u003cbr/\u003e\u003cb\u003eGames\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo_game\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"assets/demo_fire.gif\" alt=\"DOOM Fire\" /\u003e\u003cbr/\u003e\u003cb\u003eDOOM Fire Effect\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --release --example demo_fire\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" colspan=\"3\"\u003e\u003cimg src=\"assets/demo_pretext.gif\" alt=\"Pretext Reflow\" /\u003e\u003cbr/\u003e\u003cb\u003e\u003ca href=\"https://github.com/chenglou/pretext\"\u003ePretext\u003c/a\u003e Reflow\u003c/b\u003e — text reflows around the mouse cursor in real time\u003cbr/\u003e\u003csub\u003e\u003ccode\u003ecargo run --example demo_pretext\u003c/code\u003e\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Quick Start\n\n```sh\ncargo add superlighttui\n```\n\n```rust\nfn main() -\u003e std::io::Result\u003c()\u003e {\n    slt::run(|ui: \u0026mut slt::Context| {\n        ui.text(\"hello, world\");\n    })\n}\n```\n\n5 lines. No `App` trait. No `Model`/`Update`/`View`. No manual event loop. Ctrl+C just works.\n\nMSRV: Rust 1.81. Default features enable the `crossterm` backend.\n\n## 60-Second Grammar\n\nThere are four ideas most apps start with:\n\n1. State lives in normal Rust variables or structs.\n2. Layout is mostly `row()`, `col()`, and `container()`.\n3. Styling is method chaining.\n4. Interactive widgets usually return `Response`.\n\n```rust\nui.bordered(Border::Rounded).title(\"Status\").p(1).gap(1).col(|ui| {\n    ui.text(\"SLT\").bold().fg(Color::Cyan);\n    ui.row(|ui| {\n        ui.text(\"mode:\");\n        ui.text(\"ready\").fg(Color::Green);\n        ui.spacer();\n        if ui.button(\"Quit\").clicked {\n            ui.quit();\n        }\n    });\n});\n```\n\nThat is the core mental model. Everything else is depth, not a second framework.\n\n## A Real App\n\n```rust\nuse slt::{Border, Color, Context, KeyCode};\n\nfn main() -\u003e std::io::Result\u003c()\u003e {\n    let mut count: i32 = 0;\n\n    slt::run(|ui: \u0026mut Context| {\n        if ui.key('q') {\n            ui.quit();\n        }\n        if ui.key('k') || ui.key_code(KeyCode::Up) {\n            count += 1;\n        }\n        if ui.key('j') || ui.key_code(KeyCode::Down) {\n            count -= 1;\n        }\n\n        ui.bordered(Border::Rounded).title(\"Counter\").p(1).gap(1).col(|ui| {\n            ui.text(\"Counter\").bold().fg(Color::Cyan);\n            ui.row(|ui| {\n                ui.text(\"Count:\");\n                let color = if count \u003e= 0 { Color::Green } else { Color::Red };\n                ui.text(format!(\"{count}\")).bold().fg(color);\n            });\n            ui.text(\"k +1 / j -1 / q quit\").dim();\n        });\n    })\n}\n```\n\n## Runtime Modes\n\nThe same closure runs across several entry points. Pick one based on UI shape, not size.\n\n| Mode | API | When to use |\n|------|-----|-------------|\n| Full-screen | `slt::run` / `slt::run_with` | Standard TUI app — alternate screen, mouse, theme. |\n| Inline | `slt::run_inline` / `slt::run_inline_with` | Fixed-height widget below the prompt — no alternate screen. |\n| Static + inline | `slt::run_static` | Log lines stream into scrollback while an inline UI stays live below. |\n| Async messages | `slt::run_async` *(feature: `async`)* | Background tasks push messages into the closure via `tokio::mpsc`. |\n| Custom backend | `slt::frame` + `Backend` + `AppState` | Drive rendering yourself — tests, GUI embeds, WASM, snapshot harnesses. |\n\n`RunConfig` tunes mouse, kitty keyboard, color depth, max FPS, scroll speed, theme, and title across every mode.\n\n## Feature Flags\n\n```toml\n[dependencies]\nsuperlighttui = { version = \"0.21\", features = [\"async\", \"image\"] }\n```\n\n| Feature | What it adds |\n|---------|--------------|\n| `async` | `tokio` + `run_async` for background message loops |\n| `serde` | `Serialize`/`Deserialize` on selected state types |\n| `image` | PNG/JPEG decoding for `ui.image` |\n| `qrcode` | QR code rendering |\n| `kitty-compress` | zlib compression for the Kitty image protocol |\n| `syntax` | Tree-sitter highlighting for all bundled languages |\n| `syntax-\u003clang\u003e` | Highlighting for a single language (`rust`, `python`, `typescript`, ...) |\n| `full` | `async + serde + image + qrcode + kitty-compress` — **does not** include `syntax` (grammars are heavy; opt in explicitly) |\n\n## Why SLT\n\n- **Small public grammar**. Most screens start with normal Rust state, `row()` / `col()` / `container()`, method chaining, and `Response`.\n- **Less framework ceremony**. Many apps do not need an app trait, retained tree, or message enum just to get moving.\n- **Batteries included, backend still serious**. Common widgets auto-wire focus, hover, click, and scroll behavior, while the runtime keeps a conservative low-level path through `Backend`, `AppState`, and `frame()`.\n- **Conservative internals**. SLT keeps the public surface small, but the internals stay deliberately boring: shared frame kernel, explicit backend contract coverage, zero `unsafe`, feature-gated runtime paths, and validation across `all-features`, `no-default-features`, WASM, clippy, examples, cargo-hack, semver, and deny checks.\n\nFor Rust users, that usually means less setup than retained-mode TUI frameworks.\nFor AI-assisted workflows, it means the public grammar is easy to infer from docs and examples.\n\nSLT fits best when you want to build terminal apps quickly without giving up Rust type safety or backend escape hatches.\nIf you want a retained component tree or a GUI-first toolkit, another library may be a better fit.\n\n## How It Renders\n\nSLT's rendering pipeline is why the grammar stays small.\nYour code only touches the first stage — the engine handles the rest.\n\n```mermaid\ngraph LR\n    subgraph your_code [\"Your Code\"]\n        A[\"Closure\"]\n    end\n    subgraph engine [\"SLT Engine\"]\n        B[Commands] --\u003e C[Build Tree] --\u003e D[Flexbox] --\u003e E[Collect] --\u003e F[Render] --\u003e G[\"Diff + Flush\"]\n    end\n    A --\u003e|\"records intent\"| B\n    G -.-\u003e|\"prev-frame feedback\"| A\n```\n\nEvery `ui.*()` call records a command to a flat list — no tree construction, no layout math.\nThe engine replays those commands through a **four-stage DFS pipeline** — each stage specializes: build the layout tree, compute flexbox, collect interaction and feedback data, render cells to a back buffer — then diffs against the previous frame and flushes only what changed.\n\nThis architecture is what makes the simple grammar possible:\n\n- **No ceremony.** Immediate-mode means no `App` trait, no `Model`/`Message`/`Update`/`View`. Your closure is the entire UI. State is normal Rust variables. Control flow is `if`/`for`.\n- **Invisible layout.** `ui.col(|ui| { ... })` records an \"open column\" command. The engine builds the tree and runs flexbox — you never see `LayoutNode`.\n- **Automatic performance.** The double-buffer diffs cells between frames and only emits changed ANSI attributes. You redraw everything; the engine makes it fast. No manual dirty tracking.\n- **Auto-wired interaction.** `ui.button(\"Save\")` gives you hover, click, and focus for free. The collect stage fused seven independent sub-walks (hit areas, focus rects, scroll regions, group rects, content rects, focus groups, raw-draw rects) into one DFS — so the top-level pipeline is four passes, not ten.\n- **Synchronous feedback.** Interaction uses the previous frame's layout positions (imperceptible at 60 FPS). No callbacks, no async layout queries — your code stays linear.\n\nFor the full eight-stage lifecycle, see [Architecture Guide].\n\n## Common API Surface\n\nStateless calls take values; stateful widgets take an explicit state struct so your data\nkeeps living in normal Rust variables across frames.\n\n```rust\n// Text and layout\nui.text(\"Hello\").bold().fg(Color::Cyan);\nui.row(|ui| {\n    ui.text(\"left\");\n    ui.spacer();\n    ui.text(\"right\");\n});\n\n// Inputs and actions\nui.text_input(\u0026mut input);          // input: TextInputState\nif ui.button(\"Save\").clicked {}\nui.checkbox(\"Dark mode\", \u0026mut dark);\n\n// Data and navigation\nui.tabs(\u0026mut tabs);                 // tabs: TabsState\nui.list(\u0026mut list);                 // list: ListState\nui.table(\u0026mut table);               // table: TableState\nui.command_palette(\u0026mut palette);   // palette: CommandPaletteState\n\n// Overlays and rich output\nui.toast(\u0026mut toasts);              // toasts: ToastState\nui.modal(|ui| {\n    ui.text(\"Confirm?\").bold();\n});\nui.markdown(\"# Hello **world**\");\n\n// Visualization\nui.chart(|c| {\n    c.line(\u0026data);\n    c.grid(true);\n}, 50, 16);\nui.sparkline(\u0026values, 16);\nui.canvas(40, 10, |cv| {\n    cv.circle(20, 20, 15);\n});\n```\n\nState structs (`ListState`, `TableState`, `TextInputState`, `TabsState`, `CommandPaletteState`,\n`ToastState`, `FilePickerState`, `RichLogState`, ...) are public — keep them in your app\nstruct or local variables and pass them in each frame.\n\nFor the categorized widget list, see [Widget Guide].\nFor composition advice, see [Patterns Guide].\n\n## Learn The Library\n\n| Document | What it covers |\n|----------|----------------|\n| [Quick Start] | Install, first app, closure mental model, layout, widget state |\n| [Widget Guide] | Complete API catalog of widgets, runtime methods, and state types |\n| [Patterns Guide] | State placement, screen composition, helper extraction, large-app structure |\n| [Examples Guide] | Runnable examples grouped by product shape and feature area |\n| [Backends Guide] | `Backend`, `AppState`, `frame()`, inline mode, static output |\n| [Testing Guide] | `TestBackend`, `EventBuilder`, multi-frame tests, backend contract tests |\n| [Debugging Guide] | F12 overlay, clipping, focus surprises, previous-frame behavior |\n| [AI Guide] | Fastest path for AI-assisted builders and coding agents |\n| [Architecture Guide] | Module map, frame lifecycle, layout/render pipeline |\n| [Features Guide] | Feature flags, optional dependencies, recommended combos |\n| [Animation Guide] | Tween, spring, keyframes, sequence, stagger |\n| [Theming Guide] | Theme struct, presets, ThemeBuilder, custom themes |\n| [Design Principles] | API constraints and design philosophy |\n| [API Design] | Five consistency rules for new widgets and PR review checklist |\n\n## Representative Examples\n\n| Example | Command | Focus |\n|---------|---------|-------|\n| `hello` | `cargo run --example hello` | Smallest possible app |\n| `counter` | `cargo run --example counter` | State + keyboard input |\n| `demo` | `cargo run --example demo` | Broad widget tour |\n| `demo_dashboard` | `cargo run --example demo_dashboard` | Dashboard layout |\n| `demo_cli` | `cargo run --example demo_cli` | CLI tool layout |\n| `demo_infoviz` | `cargo run --example demo_infoviz` | Charts and data viz |\n| `demo_game` | `cargo run --example demo_game` | Immediate-mode interaction |\n| `demo_design_system` | `cargo run --example demo_design_system` | Design tokens, theming, style inheritance |\n| `inline` | `cargo run --example inline` | Inline rendering below a normal prompt |\n| `async_demo` | `cargo run --example async_demo --features async` | Background messages |\n\nThe full categorized index — including per-release feature tours and showcase demos — lives in [Examples Guide].\n\n### Demo Launcher\n\n`scripts/ghostty_demos.sh` opens demos in fresh Ghostty windows, which is\nuseful for skimming the full set side by side. See [Examples Guide] for the\nlist of demos at each release.\n\n```bash\n./scripts/ghostty_demos.sh             # interactive picker\n./scripts/ghostty_demos.sh --features  # full feature-tour spread\n./scripts/ghostty_demos.sh --showcase  # integration showcases only\n```\n\n## Custom Widgets And Backends\n\n- Implement `Widget` when you want reusable high-level building blocks.\n- Implement `Backend` and drive `frame()` when you want a non-terminal target, external event loop, or embedded runtime.\n- Use `TestBackend` for headless rendering checks and stable interaction tests.\n\nThe public grammar stays small even when you need the escape hatches.\n\n## Contributing\n\nRead [Contributing], then [Design Principles] and [Architecture Guide].\nThe release process expects format, check, clippy, tests, examples, and backend gates to stay green.\n\n## License\n\n[MIT](LICENSE)\n\n\u003c!-- Badge definitions --\u003e\n[Crate Badge]: https://img.shields.io/crates/v/superlighttui?style=flat-square\u0026logo=rust\u0026color=E05D44\n[Docs Badge]: https://img.shields.io/docsrs/superlighttui?style=flat-square\u0026logo=docs.rs\n[CI Badge]: https://img.shields.io/github/actions/workflow/status/subinium/SuperLightTUI/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\n[MSRV Badge]: https://img.shields.io/crates/msrv/superlighttui?style=flat-square\u0026label=MSRV\n[Downloads Badge]: https://img.shields.io/crates/d/superlighttui?style=flat-square\n[License Badge]: https://img.shields.io/crates/l/superlighttui?style=flat-square\u0026color=1370D3\n\n\u003c!-- Link definitions --\u003e\n[CI]: https://github.com/subinium/SuperLightTUI/actions/workflows/ci.yml\n[Crate]: https://crates.io/crates/superlighttui\n[Docs Index]: docs/README.md\n[Docs]: https://docs.rs/superlighttui\n[Backends Guide]: docs/BACKENDS.md\n[Testing Guide]: docs/TESTING.md\n[Debugging Guide]: docs/DEBUGGING.md\n[AI Guide]: docs/AI_GUIDE.md\n[Quick Start]: docs/QUICK_START.md\n[Widget Guide]: docs/WIDGETS.md\n[Examples Guide]: docs/EXAMPLES.md\n[Patterns Guide]: docs/PATTERNS.md\n[Architecture Guide]: docs/ARCHITECTURE.md\n[Design Principles]: docs/DESIGN_PRINCIPLES.md\n[API Design]: docs/API_DESIGN.md\n[Animation Guide]: docs/ANIMATION.md\n[Theming Guide]: docs/THEMING.md\n[Features Guide]: docs/FEATURES.md\n[Contributing]: CONTRIBUTING.md\n[License]: ./LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubinium%2Fsuperlighttui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubinium%2Fsuperlighttui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubinium%2Fsuperlighttui/lists"}