ttui 2.0.0

A terminal UI framework built from first principles: direct control over text rendering, color, pane layout, and multiplexing.
Documentation

TTUI — Tate's Terminal User Interface

crates.io docs.rs CI MSRV License: MIT

A terminal UI framework built from first principles: direct control over text rendering, color, pane layout, and multiplexing.

You own your state. TTUI owns the loop, the compositing, and the terminal — and only redraws the cells that actually changed.

Install

cargo add ttui

Or in Cargo.toml:

[dependencies]
ttui = "2.0"

Quick start

An app is one type implementing App:

use crossterm::event::{Event, KeyCode};
use ttui::app::{run, App};
use ttui::buffer::LayerStack;
use ttui::layout::Rect;
use ttui::widgets::text::Text;

struct Hello {
    quit: bool,
}

impl App for Hello {
    fn update(&mut self, event: &Event) {
        if let Event::Key(key) = event {
            if key.code == KeyCode::Char('q') {
                self.quit = true;
            }
        }
    }

    fn view(&self, area: Rect, buf: &mut LayerStack) {
        Text::new("hello, terminal — press q to quit").render(area, buf);
    }

    fn should_quit(&self) -> bool {
        self.quit
    }
}

fn main() -> std::io::Result<()> {
    run(&mut Hello { quit: false })
}

run enables raw mode and installs a panic hook that restores the terminal, so a panic doesn't leave the user's shell wrecked.

How it fits together

App state ──view()──▶ LayerStack ──composite()──▶ Buffer ──diff()──▶ terminal
    ▲                                                                    │
    └──────────────── update(event) / on_tick(elapsed) ◀─────────────────┘
  • Layered buffers — layers composite top-to-bottom by alpha, so an effects layer can sit over a UI layer without either knowing about the other.
  • Stateless widgets — a widget is handed an area and a buffer and draws. It never holds selection or scroll state, so your app stays the single source of truth.
  • Constraint layout — Rects are split by Fixed/Percentage/Fill constraints. No widget computes its own position.
  • Real-time animation — Transition tracks actual elapsed time as 0.0..=1.0 progress, and Phases subdivides it into named stages without writing every boundary twice.

Beyond the core: sub-cell drawing (half-block and braille), fixed-forward 3D projection, particle systems, glitch and screen-shake effects, a key/chord input binder, and data-viz widgets.

Status

v2.0.0. The core render pipeline, constraint layout, alpha-compositing buffer layering, and a full widget set — Text/List/Table/Block plus glitch effects, particles, a perspective camera, a chord input binder, and data-viz widgets — are implemented and exercised by ten example apps and the showcase demo reel.

v2.0 is a breaking release: Intensity, CanvasMode, Direction and Constraint are now #[non_exhaustive], so an exhaustive downstream match needs a wildcard arm; the blend module is removed in favor of LayerStack::composite and easing::scale_color; Table::new no longer takes a col_width argument — columns are sized with Constraints via .widths(&[...]) instead; and List, Dial and Table now accept an optional .theme(&theme) for their selection highlight. See CHANGELOG.md for the full migration table.

See CHANGELOG.md for the full release history.

Try the examples

From a checkout:

cargo run --bin showcase             # flagship demo reel: five vignettes
cargo run --example demo             # nested panes, Tab focus, list + table
cargo run --example launcher         # cross-app portal nexus
cargo run --example falcon           # cockpit: starfield, HUD, glitch burst
cargo run --example mission_control  # animated telemetry dashboard
cargo run --example control_panel    # click-driven console: toggles, dial

See examples/README.md for the full list and what each one demonstrates.

Minimum supported Rust version

1.87.0. Verified rather than assumed: 1.87 is the first release with unsigned_is_multiple_of stable, and 1.86 fails to compile the library.

An MSRV bump is treated as a minor version bump, not a patch.

Documentation

  • API docs on docs.rs
  • examples/README.md — what each example app demonstrates
  • Design docs — the living index of design Arcs, and how specs, plans and tasks relate. The design tree lives in the repository and is not shipped in the published crate.

Contributing

See CONTRIBUTING.md for how to build, test, and what the four required checks are. Bug reports and feature requests go through the issue templates.

This project is developed using superpowers — every feature goes through brainstorm → design doc → plan → subagent-driven implementation. Project-specific conventions layered on top of that live in .claude/rules/.

Security

See SECURITY.md for how to report a vulnerability.

License

MIT — see LICENSE.