🌀 hbh-cli.s

A lightweight CLI spinner library for Node.js featuring 70+ spinners and customizable animations. Perfect for adding visual feedback in command-line tools or scripts.

Table of Contents

• Installation

• Features

• Usage

  • Basic Usage
  • Run a Single Spinner
  • Run All Spinners
  • CLI Interactive Mode

• API

  • renderSpinnerCLI(conf)
  • startSpinnerByName(name, options)
  • runOne(conf)
  • runAllSpinnersCLI(interval, duration)
  • SpinnerController

• Custom Spinners

• License

Installation

Install via npm:

npm install hbh-cli.s

Or using yarn:

yarn add hbh-cli.s

Features

• 70+ prebuilt spinners: Arrows, Bars, Waves, Rockets, Hearts, Emoji animations, and more.
• Flexible CLI usage: Interactive spinner selection or programmatic control.
• Customizable: Control interval, duration, and frame events (render, stop, play, pause).
• Looping & smooth animations: With generator-based frame loops.
• Lightweight: No heavy dependencies, minimal footprint.

Usage

Basic Usage

import { renderSpinnerCLI } from 'hbh-cli.s';

const spinner = renderSpinnerCLI({
  name: 'Rocket', 
  interval: 100,
  events: {
    render: frame => process.stdout.write(`\r${frame} Launching...`),
    stop: () => console.log('\n🚀 Done!'),
  }
});

setTimeout(() => spinner.stop(), 5000); // Stop after 5 seconds

Run a Single Spinner

import { runOne } from 'hbh-cli.s';

await runOne({
  name: 'Rocket',
  interval: 80,
  timeout: 5000,
  events: {
    render: f => process.stdout.write(`\r${f} launching...`),
    stop: () => console.log('\n🚀 Liftoff complete!'),
  }
});

• timeout determines how long the spinner runs (ms).
• events allows custom handlers for render, stop, etc.

Run All Spinners Sequentially

import { runAllSpinnersCLI } from 'hbh-cli.s';

await runAllSpinnersCLI(100, 3000); 

• Runs all available spinners one by one in the terminal.
• interval sets frame update speed.
• duration sets how long each spinner runs.

CLI Interactive Mode

import { CLI } from 'hbh-cli.s';

// Starts an interactive spinner menu
CLI.start;

• Lists all available spinners.

• Choose a spinner by number or name.

• Controls:

  • [p] to pause/resume
  • [q] to quit

API

renderSpinnerCLI(conf)

Renders a spinner in CLI.

Parameters:

interface SpinnerConfig {
  name?: string;           // Spinner name (default: 'Dots')
  interval?: number;       // Frame interval in ms (default: 100)
  events?: {               // Event callbacks
    render?: (frame) => void,
    stop?: () => void,
    play?: () => void,
    pause?: () => void
  }
}

Returns: SpinnerController instance.

startSpinnerByName(name, options)

Start a spinner programmatically by name.

const spinner = startSpinnerByName('Rocket', { interval: 80 });
spinner.play();

runOne(conf)

Runs a single spinner asynchronously. See Run a Single Spinner.

runAllSpinnersCLI(interval, duration)

Runs all spinners sequentially in the CLI. See Run All Spinners.

SpinnerController

Controls a spinner instance programmatically.

const spinner = renderSpinnerCLI({ name: 'Dots' });

spinner.pause();
spinner.play();
spinner.stop();
spinner.restart();
spinner.isPlaying(); // true/false

Custom Spinners

You can use your own frame arrays:

import { SpinnerController } from 'hbh-cli.s';

const frames = ['😀','😃','😄','😁'];
const spinner = SpinnerController({
  generatorFn: function* () {
    let i = 0;
    while (true) yield frames[i++ % frames.length];
  },
  interval: 200,
  events: {
    render: f => process.stdout.write(`\r${f} `)
  }
});

spinner.play();

Or use SpinnerGenerator.js:

import { Generator } from 'hbh-cli.s';

const rocketFrames = Generator.Rocket({ rocket: '🚀', length: 6 });
console.log(rocketFrames);

License

ISC License