ASCII Animations
Add motion that improves feedback and personality without breaking terminal compatibility, accessibility, or non-interactive use.
Choose the smallest useful effect
- Use a spinner for indeterminate work.
- Use progress text or a bar when progress is measurable.
- Use a short splash animation only at intentional product moments.
- Use full-screen effects only when the animation is the experience.
- Keep logs and piped output static.
Common libraries
| Language | Lightweight feedback | Full TUI/effects |
|---|---|---|
| Go | briandowns/spinner |
Bubble Tea, Lip Gloss |
| JavaScript/TypeScript | ora, cli-spinners |
Ink |
| Rust | indicatif |
Ratatui, TachyonFX |
| Python | yaspin |
Textual, asciimatics |
Prefer an existing project dependency or native framework facility before adding another animation library.
Implementation rules
- Detect whether stdout is an interactive terminal.
- Disable motion for
NO_COLOR,TERM=dumb, CI, redirected output, and an explicit--no-animationoption. - Never make animation the only signal that work succeeded or failed.
- Hide the cursor only while animating and restore it with cleanup handlers on success, error, cancellation, and interrupts.
- Render frames into memory and write each frame in one operation.
- Update only changed lines instead of repeatedly clearing the whole screen.
- Use elapsed-time frame selection so slow frames do not permanently drift.
- Cap refresh rates; spinners rarely need more than 10–15 frames per second.
- Test narrow terminals, Unicode-disabled environments, and interrupted runs.
Portable frame format
For custom reusable animations, prefer plain JSON:
{
"interval_ms": 100,
"frames": ["⠋", "⠙", "⠹", "⠸"]
}
Keep a basic ASCII fallback such as | / - \\ for environments without Unicode.
Verification
Run the relevant tests and manually verify interactive, redirected, disabled, and interrupted behavior. Report any terminal-specific assumptions introduced.