CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cli-spinners

Spinners for use in the terminal

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

CLI Spinners

CLI Spinners provides a comprehensive collection of 88 terminal spinner animations for command-line interfaces and console applications. The package serves as a data library containing spinner definitions with timing intervals and frame sequences using Unicode characters, ASCII art, and various visual patterns.

Package Information

  • Package Name: cli-spinners
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install cli-spinners
  • Node.js Requirements: >=18.20

Core Imports

import cliSpinners from "cli-spinners";
import { randomSpinner } from "cli-spinners";

For TypeScript:

import cliSpinners, { randomSpinner, SpinnerName, Spinner } from "cli-spinners";

Basic Usage

import cliSpinners, { randomSpinner } from "cli-spinners";

// Access a specific spinner
console.log(cliSpinners.dots);
// {
//   interval: 80,
//   frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
// }

// Get a random spinner
const spinner = randomSpinner();
console.log(spinner);
// {
//   interval: 80,
//   frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
// }

// Use with a terminal spinner library (like ora)
import ora from 'ora';
const loading = ora({
  text: 'Loading...',
  spinner: cliSpinners.dots
}).start();

Capabilities

Spinner Collection

The default export provides access to all 88 available spinner animations. Each spinner contains recommended timing and frame data optimized for terminal display.

/**
 * Collection of 88 spinner definitions for terminal animations.
 * Each spinner provides interval timing and frame sequences.
 */
declare const cliSpinners: {
  readonly [spinnerName in SpinnerName]: Spinner;
};

export default cliSpinners;

Available Spinner Names (88 total):

dots, dots2, dots3, dots4, dots5, dots6, dots7, dots8, dots9, dots10, dots11, dots12, dots13, dots14, dots8Bit, dotsCircle, sand, line, line2, pipe, simpleDots, simpleDotsScrolling, star, star2, flip, hamburger, growVertical, growHorizontal, balloon, balloon2, noise, bounce, boxBounce, boxBounce2, triangle, binary, arc, circle, squareCorners, circleQuarters, circleHalves, squish, toggle, toggle2, toggle3, toggle4, toggle5, toggle6, toggle7, toggle8, toggle9, toggle10, toggle11, toggle12, toggle13, arrow, arrow2, arrow3, bouncingBar, bouncingBall, smiley, monkey, hearts, clock, earth, material, moon, runner, pong, shark, dqpb, weather, christmas, grenade, point, layer, betaWave, fingerDance, fistBump, soccerHeader, mindblown, speaker, orangePulse, bluePulse, orangeBluePulse, timeTravel, aesthetic, dwarfFortress

Random Spinner Selection

Get a randomly selected spinner from the collection for dynamic spinner variation.

/**
 * Get a random spinner from the collection.
 * 
 * @returns A randomly selected spinner object with interval and frames
 */
export function randomSpinner(): Spinner;

Usage Example:

import { randomSpinner } from "cli-spinners";

// Get a different spinner each time
const spinner1 = randomSpinner();
const spinner2 = randomSpinner();
const spinner3 = randomSpinner();

// Use with setInterval to create animated display
let currentFrame = 0;
const randomSpinner = randomSpinner();
const interval = setInterval(() => {
  process.stdout.write(`\r${randomSpinner.frames[currentFrame]} Loading...`);
  currentFrame = (currentFrame + 1) % randomSpinner.frames.length;
}, randomSpinner.interval);

Types

/**
 * Union type of all available spinner names.
 * Includes all 88 spinner identifiers for type safety.
 */
export type SpinnerName =
  | 'dots' | 'dots2' | 'dots3' | 'dots4' | 'dots5' | 'dots6' | 'dots7' | 'dots8'
  | 'dots9' | 'dots10' | 'dots11' | 'dots12' | 'dots13' | 'dots14' | 'dots8Bit'
  | 'dotsCircle' | 'sand' | 'line' | 'line2' | 'pipe' | 'simpleDots' | 'simpleDotsScrolling'
  | 'star' | 'star2' | 'flip' | 'hamburger' | 'growVertical' | 'growHorizontal'
  | 'balloon' | 'balloon2' | 'noise' | 'bounce' | 'boxBounce' | 'boxBounce2'
  | 'binary' | 'triangle' | 'arc' | 'circle' | 'squareCorners' | 'circleQuarters'
  | 'circleHalves' | 'squish' | 'toggle' | 'toggle2' | 'toggle3' | 'toggle4'
  | 'toggle5' | 'toggle6' | 'toggle7' | 'toggle8' | 'toggle9' | 'toggle10'
  | 'toggle11' | 'toggle12' | 'toggle13' | 'arrow' | 'arrow2' | 'arrow3'
  | 'bouncingBar' | 'bouncingBall' | 'smiley' | 'monkey' | 'hearts' | 'clock'
  | 'earth' | 'material' | 'moon' | 'runner' | 'pong' | 'shark' | 'dqpb'
  | 'weather' | 'christmas' | 'grenade' | 'point' | 'layer' | 'betaWave'
  | 'fingerDance' | 'fistBump' | 'soccerHeader' | 'mindblown' | 'speaker'
  | 'orangePulse' | 'bluePulse' | 'orangeBluePulse' | 'timeTravel' | 'aesthetic'
  | 'dwarfFortress';

/**
 * Structure defining a terminal spinner animation.
 * Contains recommended timing and frame sequence data.
 */
export type Spinner = {
  /** 
   * The recommended interval.
   */
  readonly interval: number;

  /** 
   * A list of frames to show for the spinner.
   */
  readonly frames: string[];
}

Architecture

CLI Spinners follows a simple, data-driven architecture:

  • Data File: spinners.json contains all spinner definitions as structured JSON
  • ESM Module: Main module imports JSON data using import assertions (with {type: 'json'})
  • Default Export: Direct export of spinner data object for property access
  • Named Export: Single utility function for random selection
  • Type Definitions: Complete TypeScript support with specific spinner name types
  • Frame Consistency: All frames within each spinner maintain consistent visual width
  • No Dependencies: Zero runtime dependencies for maximum compatibility

Common Patterns

Integration with Terminal UI Libraries

import ora from 'ora';
import cliSpinners from 'cli-spinners';

// Use specific spinner
const spinner = ora({
  text: 'Processing data...',
  spinner: cliSpinners.material
}).start();

// Use random spinner
const randomSpinner = ora({
  text: 'Loading...',
  spinner: randomSpinner()
}).start();

Custom Animation Loop

import cliSpinners, { randomSpinner } from 'cli-spinners';

function animateSpinner(text = 'Loading...', duration = 5000) {
  const spinner = randomSpinner();
  let currentFrame = 0;
  
  const interval = setInterval(() => {
    process.stdout.write(`\r${spinner.frames[currentFrame]} ${text}`);
    currentFrame = (currentFrame + 1) % spinner.frames.length;
  }, spinner.interval);
  
  setTimeout(() => {
    clearInterval(interval);
    process.stdout.write('\r✅ Complete!\n');
  }, duration);
}

animateSpinner('Processing files...', 3000);

Frame Width Consistency

All frames within a spinner maintain consistent visual width, making them suitable for fixed-position terminal displays:

import cliSpinners from 'cli-spinners';

// All frames in 'dots' have the same visual width
const { frames } = cliSpinners.dots;
console.log(frames); // ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']

// Safe to use in fixed-width terminal layouts
frames.forEach(frame => {
  console.log(`[${frame}] Status: Processing...`);
});

Install with Tessl CLI

npx tessl i tessl/npm-cli-spinners
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cli-spinners@3.2.x
Publish Source
CLI
Badge
tessl/npm-cli-spinners badge