tui-splitflap

A Ratatui widget for rendering retro split-flap display boards in the terminal.

Animated character tiles that cycle through an ordered character set, just like the mechanical departure boards at airports and train stations.

demo

Features

Three animation styles — Sequential (character roll), Mechanical (split-block), and Combined
Staggered flips — configurable delay between adjacent cells for a wave effect
Multi-row boards — display multiple lines of text
Mid-flip interrupts — new messages resolve cleanly from the current animation state
Theming — customizable colors for text, tile background, borders, and split animation
Block integration — wrap the board in a ratatui Block for titled borders

Installation

cargo add tui-splitflap

Usage

use tui_splitflap::{FlapBoard, FlapBoardState, FlapMessage, FlipStyle};

let mut state = FlapBoardState::new(1, 20)
    .with_flip_style(FlipStyle::Combined { frames: 3 })
    .with_flip_speed_ms(60)
    .with_stagger_ms(15);

state.set_message(&FlapMessage::single("HELLO WORLD"));

In your event loop, call state.tick(delta_ms) (returns true while animating) and render with frame.render_stateful_widget(FlapBoard::new(), area, &mut state).

Animation Styles

Style	Description
`Sequential`	Cycles through each intermediate character. Duration scales with distance.
`Mechanical { frames }`	Fixed split-block animation. Constant duration regardless of distance.
`Combined { frames }`	Mechanical phase first, then sequential roll to landing.

Examples

Interactive demo

cargo run --example demo

Keys: [space] next message · [m] mode · [s] speed · [t] theme · [r] reset · [q] quit

Widget pantry

Browse widget variants in the tui-pantry isolation viewer:

cargo pantry

Or without cargo-pantry installed:

cargo run --example widget_preview --features pantry

License

Dual licensed under MIT or Apache 2.0.

Contributing

Contributions are welcome. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be dual licensed as above, without any additional terms or conditions.

tui-splitflap 0.1.0