Skip to main content

Crate ttui

Crate ttui 

Source
Expand description

ttui — a terminal UI framework built around layered buffers, Transition-driven animation, and dumb (no-internal-state) widgets.

§Quick start

An app is one type implementing App. You own the state; ttui owns the loop, the diffing, and the terminal.

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, installs a panic hook that restores the terminal, and only redraws cells that actually changed.

§How it fits together

App state ──view()──▶ LayerStack ──composite()──▶ Buffer ──diff()──▶ terminal
    ▲                                                                    │
    └──────────────── update(event) / on_tick(elapsed) ◀─────────────────┘
  • buffer — Cell, Buffer and LayerStack, the render target. Layers composite top-to-bottom by alpha, so an effects layer can sit over a UI layer without either knowing about the other.
  • layout — splits a Rect by Constraints. No widget computes its own position.
  • widgets — stateless renderers. 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.
  • transition — Transition tracks real elapsed time as 0.0..=1.0 progress, and Phases subdivides that progress into named stages without writing every boundary twice.
  • theme — one palette and border set threaded through widgets.

Beyond the core: canvas (sub-cell half-block and braille drawing), perspective (fixed-forward 3D projection), particles, glitch, effects, camera, input (key chords), easing, noise and audio.

§Animation

Return a tick_rate and ttui calls on_tick with the real elapsed time, so animation stays correct when a frame runs long:

use std::time::Duration;
use ttui::transition::{Phases, Transition};

// Three stages across one 900ms transition: 20% fade in, 60% hold,
// 20% fade out. Boundaries are written once, not twice.
const STAGES: Phases<3> = Phases::new([0.2, 0.8, 1.0]);

let t = Transition::start(Duration::from_millis(900));
let (stage, progress_within) = STAGES.at(t.progress());
assert!(stage < 3);
assert!((0.0..=1.0).contains(&progress_within));

§Examples

The repository carries ten runnable example apps and a showcase demo reel. From a checkout:

cargo run --bin showcase        # mascot-hosted reel of five vignettes
cargo run --example demo        # nested panes, Tab focus, list + table
cargo run --example falcon      # cockpit: starfield, HUD, glitch effects

See examples/README.md for what each one demonstrates.

Modules§

app
Terminal event loop and the App trait apps implement. Terminal event loop: polls input, dispatches to an App, and redraws only the cells that changed since the last frame.
audio
AudioSink trait for optional sound-effect playback. Optional sound-effect playback hook — apps depend on AudioSink rather than a concrete audio backend so they stay testable/silent by default.
buffer
Cell/Buffer/LayerStack — the framework’s core render target. Cell/Buffer/LayerStack — the framework’s core render target. Widgets write Cells into a Buffer; apps composite multiple layers into one via LayerStack before the terminal diff-flush.
camera
Deterministic camera viewport and brightness scaling. Deterministic camera viewport and brightness scaling — used for panning/zooming a rendered buffer and for boot-sequence fades.
canvas
Sub-cell rendering primitive (half-block + braille) — graduated, committed API; see the module docs for HalfBlock vs Braille details. Sub-cell rendering primitive: HalfBlock mode gives 2x vertical resolution with full 2-color fidelity per cell; Braille mode gives 4x resolution with one fg color per cell. Graduated from the rendering-fidelity spike (docs/design/specs/core/2026-08-08-rendering-fidelity-spike-design.md) per docs/design/specs/core/2026-08-08-rendering-primitives-graduation-design.md.
easing
Linear/eased interpolation and progress helpers. Linear/eased interpolation and progress helpers — the building blocks every Transition-driven animation in this codebase uses.
effects
Screen-shake and other whole-buffer visual effects. Screen-shake and other whole-buffer visual effects.
glitch
Decaying noise overlay for glitch/corruption effects. Decaying noise overlay for glitch/corruption effects — shared across screens that render mutually-exclusive glitch states.
input
Key-binding resolver: single keys and multi-key chords resolving to an app-defined action type. Framework-level key-binding resolver: single keys and multi-key chords resolve to an app-defined action type. Apps compose an InputBinder into their own state (like GlitchBuffer/ ParticleSystem) rather than the App trait changing shape.
layout
Rect/Constraint-based area splitting. Rect/Constraint-based area splitting, in the same spirit as ratatui’s Layout — divides one area into ordered sub-areas.
noise
Deterministic seed-driven jitter for scattering and placement. Deterministic seed-driven jitter — one integer hash, no RNG state and no allocation, so the same seed gives the same offset on every frame and every run. Not a general-purpose PRNG and not cryptographic: it exists to place stars and nudge glyphs.
particles
A simple particle system for bursts and impacts. A simple particle system for bursts and impacts — one straight-line velocity per particle, no gravity or collision.
perspective
Fixed-forward pinhole-camera projection: points, lines, polygons. Fixed-forward pinhole-camera projection — points, lines, and polygons in camera-relative 3D space project to 2D screen coordinates plus a depth-derived scale. Graduated from the depth & perspective projection spike (docs/design/specs/core/2026-08-10-depth-perspective-projection-spike-design.md) per docs/design/specs/core/2026-08-11-perspective-projection-graduation-design.md. No camera position/orientation — see that spec’s Non-goals.
terminal
Raw-mode terminal setup/teardown. Raw-mode terminal setup/teardown: entering the alternate screen, diff-based redraws, input polling, and panic-safe cleanup.
theme
App color palette and border glyph set. App color palette and border glyph set — passed explicitly to Block/SmashBorder; other widgets take plain color params instead of a whole Theme.
transition
Time-driven progress tracking for animations, and the Phases subdivision of a progress range. Time-driven progress tracking for animations — apps own a Transition per animated value, tick it each frame, and read progress()/is_complete() to drive rendering. Phases lives beside it because the two are read together — PHASES.at(t.progress()) turns one overall progress into a phase index and progress within that phase — not because this module owns animation staging.
widgets
Ready-to-render widgets — see widgets module docs. Ready-to-render TUI widgets — each takes an explicit value/theme and a target area, no internal animation state; the owning app computes any tweened value and passes a snapshot per frame.