tui-skeleton

Animated skeleton loading widgets for Ratatui.

Placeholder widgets that pulse, sweep, or shimmer while data loads. All widgets are stateless — pass elapsed_ms from your event loop and the animation state is computed purely from the timestamp.

Widgets

Installation

cargo add tui-skeleton

Usage

use ratatui_core::style::Color;
use tui_skeleton::{SkeletonBlock, AnimationMode};

// Solid fill with sweep animation
let solid = SkeletonBlock::new(elapsed_ms)
    .mode(AnimationMode::Sweep)
    .base(Color::Rgb(30, 22, 58))
    .highlight(Color::Rgb(49, 40, 78));

// Braille fill (⣿) with breathe animation
let braille = SkeletonBlock::new(elapsed_ms)
    .braille(true)
    .base(Color::Rgb(30, 22, 58))
    .highlight(Color::Rgb(49, 40, 78));

// TV noise — random braille glyphs changing every frame
let noise = SkeletonBlock::new(elapsed_ms)
    .mode(AnimationMode::Noise);

All widgets share the same builder pattern:

use ratatui_core::layout::Constraint;
use tui_skeleton::{SkeletonTable, SkeletonList, SkeletonText};

// Table with 3 columns
let table = SkeletonTable::new(elapsed_ms)
    .columns(&[Constraint::Percentage(30), Constraint::Percentage(40), Constraint::Percentage(30)])
    .rows(8)
    .zebra(true);

// List (short spaced items)
let list = SkeletonList::new(elapsed_ms)
    .items(8);

// Paragraph placeholder
let text = SkeletonText::new(elapsed_ms)
    .line_widths(&[1.0, 1.0, 0.8, 1.0, 0.6]);

Render conditionally based on your application state:

if data.is_loading() {
    SkeletonTable::new(elapsed_ms)
        .columns(&col_constraints)
        .rows(8)
        .render(area, buf);
} else {
    my_table.render(area, buf);
}

Animation Modes

Breathe

Sweep

Plasma

Noise

Colors

All widgets accept base and highlight colors for the interpolation endpoints:

• base — dim resting state (default: DarkGray)
• highlight — peak brightness (default: Gray)

Defaults work on both dark and light terminals. Override to match your theme:

use ratatui_core::style::Color;
use tui_skeleton::SkeletonBlock;

// Dark theme
let dark = SkeletonBlock::new(elapsed_ms)
    .base(Color::Rgb(30, 22, 58))
    .highlight(Color::Rgb(49, 40, 78));

// Light theme
let light = SkeletonBlock::new(elapsed_ms)
    .base(Color::Rgb(250, 249, 253))
    .highlight(Color::Rgb(232, 230, 240));

Adaptive Tick Rate

Skeleton animations look best at ~20 FPS. The crate exports recommended intervals:

use tui_skeleton::{TICK_ANIMATED, TICK_IDLE};
// TICK_ANIMATED = 50ms  (20 FPS)
// TICK_IDLE     = 200ms (5 FPS)

The recommended pattern:

1. Track whether any skeleton is currently visible
2. Use TICK_ANIMATED when skeletons are on screen
3. Revert to TICK_IDLE when all data has loaded

Builder Methods

All widgets support:

Shape-specific:

Examples

Interactive demo

cargo run --example demo

All widget types in a 3×3 grid. [m] cycle animation modes, [b] toggle braille fill, [l] toggle skeleton↔data loop, [q] quit.

Widget pantry

This repo ships with tui-pantry integration — a widget isolation tool for ratatui. Browse every skeleton widget, all animation modes and fill variants, realistic use-case panes, and their props in an interactive 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.

See CONTRIBUTING.md for guidelines.