🪇 Rattles

Demo

Rattles is a terminal spinner library for Rust with an extensive preset collection and lets you define custom spinners at compile time.

Rattles is minimal; it makes no assumptions about how the output will be used, and just works. It also has zero dependencies.

Philosophy

Most spinner libraries are built as actors or widgets. Rattles is neither. It has no runtime, no lifecycle, and requires no integration by default.

Spinners can be constructed directly in the render loop with negligible cost. The result is a library that gets out of your way.

Quick Start

cargo add rattles

Basic usage

use std::{io::Write, time::Duration};
use rattles::presets::prelude as presets;

fn main() {
    let rattle = presets::waverows();

    // change default interval
    // let rattle = presets::waverows().set_interval(Duration::from_millis(100));

    // reverse direction
    // let rattle = presets::waverows().reverse();

    loop {
        print!("\r{}", rattle.current_frame());
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(20));
    }
}

Custom keyframes

rattle!(
    Custom, // struct name
    custom, // method name
    1,      // row count (width of the spinner)
    100,    // interval in milliseconds
    ["⣾", "⣷", "⣯", "⣟", "⣻", "⣽", "⣾"] // keyframes
)

`no_std`

rattles enables the std feature by default. To opt out:

cargo add rattles --no-default-features

Without std, the global clock is unavailable. Animations can still be driven three ways:

Time-based, with an external clock:
```
rattle.frame_at(elapsed)
```
Index-based:
```
rattle.frame(n)
```

Tick-based:

let mut rattle = presets::dots().into_ticked();
rattle.tick();
let frame = rattle.current_frame();

Note that TickedRattler is stateful and must be stored.

Presets

Built-in presets are organized by category:

presets::arrows
presets::ascii
presets::braille
presets::emoji

A prelude is available rattles::presets::prelude.

Examples

Example showcasing all presets, built with ratatui:

cargo run --example showcase

There's also a minimal no_std-oriented usage example found here.

Acknowledgements

Rattles includes spinners sourced from these wonderful projects. We gratefully acknowledge their work.

rattles 0.2.2