opentui-spinner

June 9, 2026 · View on GitHub

A small & opinionated spinner library for terminal UIs built on OpenTUI.

Features

Built-in Spinners - Powered by cli-spinners
Custom Spinners - Create your own with custom frames and intervals
React Support - First-class React integration via OpenTUI React
SolidJS Support - First-class SolidJS integration via OpenTUI Solid
Type-Safe - Full TypeScript support

Installation

bun add opentui-spinner @opentui/core

For React support:

bun add opentui-spinner @opentui/core @opentui/react react

For SolidJS support:

bun add opentui-spinner @opentui/core @opentui/solid solid-js

Usage

Interactive Examples

Each launcher includes a chooser, every built-in spinner, custom animations, and shared console/debug controls:

bun run examples
bun run examples:react
bun run examples:solid

Use Escape to return to the chooser, backtick to toggle the console, . to toggle the debug overlay, Ctrl+G to dump the hit grid, and Ctrl+C to exit.

Basic Usage (Core)

import { createCliRenderer } from "@opentui/core";
import { SpinnerRenderable } from "opentui-spinner";

const renderer = await createCliRenderer();

const spinner = new SpinnerRenderable(renderer, {
  name: "dots",
  color: "cyan",
});

renderer.root.add(spinner);

With Text Label

import {
  BoxRenderable,
  createCliRenderer,
  TextRenderable,
} from "@opentui/core";
import { SpinnerRenderable } from "opentui-spinner";

const renderer = await createCliRenderer();

const container = new BoxRenderable(renderer, {
  border: true,
  flexDirection: "row",
  alignItems: "center",
});

const spinner = new SpinnerRenderable(renderer, {
  name: "bouncingBall",
});

const label = new TextRenderable(renderer, {
  content: "Loading...",
  marginLeft: 1,
});

container.add(spinner);
container.add(label);
renderer.root.add(container);

React Usage

First, import the React extension:

import "opentui-spinner/react";

Then use the <spinner> component in your OpenTUI React app:

import { createCliRenderer } from "@opentui/core";
import { createRoot } from "@opentui/react";
import "opentui-spinner/react";

function App() {
  return (
    <box alignItems="center" flexDirection="row">
      <spinner name="bouncingBall" color="cyan" />
      <text marginLeft={1}>Loading...</text>
    </box>
  );
}

const renderer = await createCliRenderer();
createRoot(renderer).render(<App />);

SolidJS Usage

First, import the SolidJS extension:

import "opentui-spinner/solid";

Then use the <spinner> component in your OpenTUI SolidJS app:

import { render } from "@opentui/solid";
import "opentui-spinner/solid";

function App() {
  return (
    <box alignItems="center" flexDirection="row">
      <spinner name="bouncingBall" color="cyan" />
      <text marginLeft={1}>Loading...</text>
    </box>
  );
}

render(() => <App />);

API Reference

SpinnerOptions

Option	Type	Default	Description
`name`	`SpinnerName`	`"dots"`	Name of a built-in spinner from cli-spinners
`frames`	`string[]`	-	Custom animation frames (overrides `name`)
`interval`	`number`	-	Target frame interval from 16.67-1000ms
`autoplay`	`boolean`	`true`	Whether to start playing automatically
`color`	`ColorInput \| ColorGenerator`	`"white"`	Foreground color or color generator function
`backgroundColor`	`ColorInput`	`"transparent"`	Background color

SpinnerRenderable Methods

`start(): void`

Start or resume the spinner animation.

spinner.start();

`stop(): void`

Pause the spinner animation.

spinner.stop();

Properties

All options can be updated dynamically via properties:

// Change spinner type
spinner.name = "line";

// Update color
spinner.color = "green";

// Or use a color generator
spinner.color = createPulse(["red", "yellow", "green"]);

// Update background color
spinner.backgroundColor = "blue";

// Change frames
spinner.frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

// Adjust interval
spinner.interval = 100;

Intervals must be finite numbers from 1000 / 60 through 1000 milliseconds, inclusive. Invalid constructor values and property updates throw a RangeError. All running spinners share one adaptive scheduler interval, including across multiple OpenTUI renderers in the same process. Scheduler wake-ups are globally capped at 60 FPS, so staggered spinners can be delayed and run below their configured rate. Invisible spinners are suspended until shown and do not advance frames or request renders while hidden.

Performance Benchmark

Run the calibrated scheduler benchmark:

bun run bench -- --json=bench/results/latest.json

For a faster local smoke run:

bun run bench:quick

The benchmark compares the adaptive heap scheduler with its heap-only behavior, equivalent shared linear-scan workloads, and a per-spinner timer lifecycle baseline. It reports median and p95 nanoseconds per operation, operations per second, 95% relative margin of error, and maximum active timers. JSON output includes every sample, runtime and CPU information, Git state, and a correctness checksum derived from the verified scheduler behavior trace. The checksum is independent of benchmark timing, calibration, and selected scenarios.

Profile real spinner rendering with Bun's CPU profiler:

bun --cpu-prof --cpu-prof-md --cpu-prof-dir ./profiles \
  profile/spinner-cpu-profile.ts \
  --count=100 --duration-ms=15000 --interval=80 --mode=staggered

The profiling scenario uses OpenTUI's test renderer with native timers and reports process CPU time, spinner render requests, rendered frames, effective FPS, and whether rendering stayed within OpenTUI's configured 60 FPS limit. Available modes are aligned, hidden, staggered, and mixed.

Available Spinners

The library includes 80+ spinners from cli-spinners. Popular choices include:

dots - Simple dots (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
dots2 - Alternative dots
dots3 through dots12 - Various dot styles
line - Rotating line (- \ | /)
pipe - Simple pipe animation
star - Rotating star
arc - Arc animation
circle - Circle segments
squareCorners - Rotating square corners
circleQuarters - Quarter circles
circleHalves - Half circles
bouncingBar - Bouncing bar
bouncingBall - Bouncing ball
arrow - Arrow animations
hamburger - Hamburger menu animation
growVertical / growHorizontal - Growing bars
balloon / balloon2 - Balloon animations
noise / bounce - Various effects
boxBounce - Bouncing box
weather - Weather icons
moon - Moon phases
runner - Running character
pong - Pong animation
shark - Shark animation
dqpb - Letter rotation

See the full list at cli-spinners.

Custom Spinners

Create your own spinner with custom frames:

const spinner = new SpinnerRenderable(renderer, {
  frames: ["◐", "◓", "◑", "◒"],
  interval: 80,
  color: "magenta",
});

Color Options

Colors can be specified in multiple formats:

// Named colors
spinner.color = "red";
spinner.color = "cyan";

// RGB values
spinner.color = { r: 255, g: 100, b: 50 };

// Hex colors
spinner.color = "#ff6432";

Dynamic Color Effects

The color property also accepts a ColorGenerator function for dynamic color effects:

import { SpinnerRenderable, type ColorGenerator } from "opentui-spinner";

// Custom color generator
const customColorGen: ColorGenerator = (
  frameIndex,
  charIndex,
  totalFrames,
  totalChars
) => {
  // Return different colors based on frame/character position
  return frameIndex % 2 === 0 ? "cyan" : "magenta";
};

const spinner = new SpinnerRenderable(renderer, {
  name: "dots",
  color: customColorGen,
});

Built-in Color Generators

`createPulse(colors, speed?)`

Creates a pulsing effect that cycles through colors:

import { SpinnerRenderable, createPulse } from "opentui-spinner";

const spinner = new SpinnerRenderable(renderer, {
  name: "dots",
  color: createPulse(["red", "orange", "yellow"], 0.5),
});

Parameters:

colors: Array of colors to cycle through
speed: Animation speed multiplier (default: 1.0)

`createWave(colors)`

Creates a wave pattern that moves across characters:

import { SpinnerRenderable, createWave } from "opentui-spinner";

const spinner = new SpinnerRenderable(renderer, {
  name: "dots",
  color: createWave(["#ff0000", "#00ff00", "#0000ff"]),
});

Parameters:

colors: Array of colors for the wave gradient

Examples

Check out the examples/ directory for complete working examples:

examples/index.ts - Core example
examples/react.tsx - React example
examples/solid.tsx - SolidJS example

Peer Dependencies

@opentui/core (required)
@opentui/react (optional, for React support)
@opentui/solid (optional, for SolidJS support)

Development

# Install dependencies
bun install

# Build the library
bun run build

# Lint code
bun run lint

# Auto-fix linting issues
bun run lint:fix

License

MIT

Credits

Built on OpenTUI
Spinners from cli-spinners by Sindre Sorhus

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.