tui_skeleton/
lib.rs

1//! Animated skeleton loading widgets for [Ratatui](https://ratatui.rs).
2//!
3//! Provides placeholder widgets that pulse, sweep, or shimmer while data loads.
4//! All widgets are stateless — pass `elapsed_ms` from your event loop and the
5//! animation state is computed purely from the timestamp.
6//!
7//! # Widgets
8//!
9//! - [`SkeletonBlock`] — Solid filled rectangle (atomic unit)
10//! - [`SkeletonTable`] — Rows with column separators and zebra striping
11//! - [`SkeletonList`] — Short spaced items with ragged edges (menu/sidebar)
12//! - [`SkeletonText`] — Paragraph simulation with varying line widths
13//! - [`SkeletonBarChart`] — Vertical bars of varying height
14//! - [`SkeletonHBarChart`] — Horizontal bars of varying length
15//! - [`SkeletonKvTable`] — Key-value pairs (properties/detail panel)
16//! - [`SkeletonLineChart`] — Braille line chart with overlapping wave traces
17//!
18//! # Example
19//!
20//! ```rust
21//! use tui_skeleton::{SkeletonBlock, AnimationMode, Color};
22//!
23//! let elapsed_ms = 1000u64;
24//! let widget = SkeletonBlock::new(elapsed_ms)
25//!     .mode(AnimationMode::Breathe)
26//!     .base(Color::Rgb(30, 22, 58))
27//!     .highlight(Color::Rgb(49, 40, 78));
28//! ```
29//!
30//! # Adaptive Tick Rate
31//!
32//! Skeleton animations look best at ~20 FPS ([`TICK_ANIMATED`]) but most TUI
33//! applications tick at ~5 FPS ([`TICK_IDLE`]) for static content. The
34//! recommended pattern:
35//!
36//! 1. Track whether any skeleton widget is currently visible
37//! 2. Use [`TICK_ANIMATED`] when skeletons are on screen
38//! 3. Revert to [`TICK_IDLE`] when all data has loaded
39//!
40//! This keeps CPU usage low while delivering smooth animations during loading.
41
42pub(crate) mod animation;
43mod bar_chart;
44mod block;
45mod hbar_chart;
46mod kv_table;
47mod line_chart;
48mod list;
49mod table;
50mod text;
51
52pub use animation::AnimationMode;
53pub use bar_chart::SkeletonBarChart;
54pub use block::SkeletonBlock;
55pub use hbar_chart::SkeletonHBarChart;
56pub use kv_table::SkeletonKvTable;
57pub use line_chart::SkeletonLineChart;
58pub use list::SkeletonList;
59pub use table::SkeletonTable;
60pub use text::SkeletonText;
61
62// Re-export types consumers need so they never depend on ratatui-core/ratatui-widgets directly.
63pub use ratatui_core::layout::Constraint;
64pub use ratatui_core::style::Color;
65pub use ratatui_widgets::block::Block;
66
67use std::time::Duration;
68
69/// Recommended tick interval when skeleton widgets are visible (50ms / 20 FPS).
70pub const TICK_ANIMATED: Duration = Duration::from_millis(50);
71
72/// Recommended tick interval for static content (200ms / 5 FPS).
73pub const TICK_IDLE: Duration = Duration::from_millis(200);
74
75/// Default colors that work on both dark and light terminals.
76pub mod defaults {
77    use ratatui_core::style::Color;
78
79    pub const BASE: Color = Color::DarkGray;
80    pub const HIGHLIGHT: Color = Color::Gray;
81}
tui_skeleton/lib.rs

tui_skeleton/
lib.rs
