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,BufferandLayerStack, 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 aRectbyConstraints. 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—Transitiontracks real elapsed time as0.0..=1.0progress, andPhasessubdivides 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 effectsSee examples/README.md for what each one demonstrates.
Modules§
- app
- Terminal event loop and the
Apptrait apps implement. Terminal event loop: polls input, dispatches to anApp, and redraws only the cells that changed since the last frame. - audio
AudioSinktrait for optional sound-effect playback. Optional sound-effect playback hook — apps depend onAudioSinkrather 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 writeCells into aBuffer; apps composite multiple layers into one viaLayerStackbefore 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
HalfBlockvsBrailledetails. Sub-cell rendering primitive:HalfBlockmode gives 2x vertical resolution with full 2-color fidelity per cell;Braillemode 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
InputBinderinto their own state (likeGlitchBuffer/ParticleSystem) rather than theApptrait changing shape. - layout
Rect/Constraint-based area splitting.Rect/Constraint-based area splitting, in the same spirit as ratatui’sLayout— 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 wholeTheme. - transition
- Time-driven progress tracking for animations, and the
Phasessubdivision of a progress range. Time-driven progress tracking for animations — apps own aTransitionper animated value,tickit each frame, and readprogress()/is_complete()to drive rendering.Phaseslives 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
widgetsmodule 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.