opentui-spinner

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.