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//! - [`SkeletonStreamingText`] — Typewriter-style chat text filling over time
14//! - [`SkeletonBarChart`] — Vertical bars of varying height
15//! - [`SkeletonHBarChart`] — Horizontal bars of varying length
16//! - [`SkeletonKvTable`] — Key-value pairs (properties/detail panel)
17//! - [`SkeletonLineChart`] — Braille line chart with overlapping wave traces
18//!
19//! # Example
20//!
21//! ```rust
22//! use tui_skeleton::{SkeletonBlock, AnimationMode, Color};
23//!
24//! let elapsed_ms = 1000u64;
25//! let widget = SkeletonBlock::new(elapsed_ms)
26//!     .mode(AnimationMode::Breathe)
27//!     .base(Color::Rgb(30, 22, 58))
28//!     .highlight(Color::Rgb(49, 40, 78));
29//! ```
30//!
31//! # Adaptive Tick Rate
32//!
33//! Skeleton animations look best at ~20 FPS ([`TICK_ANIMATED`]) but most TUI
34//! applications tick at ~5 FPS ([`TICK_IDLE`]) for static content. The
35//! recommended pattern:
36//!
37//! 1. Track whether any skeleton widget is currently visible
38//! 2. Use [`TICK_ANIMATED`] when skeletons are on screen
39//! 3. Revert to [`TICK_IDLE`] when all data has loaded
40//!
41//! This keeps CPU usage low while delivering smooth animations during loading.
42
43pub(crate) mod animation;
44pub mod bar_chart;
45pub mod block;
46pub mod hbar_chart;
47pub mod kv_table;
48pub mod line_chart;
49pub mod list;
50pub mod table;
51pub mod streaming_text;
52pub mod text;
53
54#[cfg(feature = "pantry")]
55pub mod use_cases;
56
57pub use animation::AnimationMode;
58pub use bar_chart::SkeletonBarChart;
59pub use block::SkeletonBlock;
60pub use hbar_chart::SkeletonHBarChart;
61pub use kv_table::SkeletonKvTable;
62pub use line_chart::SkeletonLineChart;
63pub use list::SkeletonList;
64pub use streaming_text::SkeletonStreamingText;
65pub use table::SkeletonTable;
66pub use text::SkeletonText;
67
68// Re-export types consumers need so they never depend on ratatui-core/ratatui-widgets directly.
69pub use ratatui_core::layout::Constraint;
70pub use ratatui_core::style::Color;
71pub use ratatui_widgets::block::Block;
72
73use std::time::Duration;
74
75/// Recommended tick interval when skeleton widgets are visible (50ms / 20 FPS).
76pub const TICK_ANIMATED: Duration = Duration::from_millis(50);
77
78/// Recommended tick interval for static content (200ms / 5 FPS).
79pub const TICK_IDLE: Duration = Duration::from_millis(200);
80
81/// Default colors that work on both dark and light terminals.
82pub mod defaults {
83    use ratatui_core::style::Color;
84
85    pub const BASE: Color = Color::DarkGray;
86    pub const HIGHLIGHT: Color = Color::Gray;
87}
tui_skeleton/lib.rs

tui_skeleton/
lib.rs
