Registry / observability / cli-spinners

cli-spinners

JSON →
library3.4.0jsnpmunverified

cli-spinners is a JavaScript/TypeScript library that provides a comprehensive collection of over 70 distinct, pre-defined terminal spinners. Each spinner entry includes a recommended `interval` (in milliseconds) for frame display and an array of Unicode `frames` that constitute the animation sequence. The package's current stable version is 3.4.0, and it maintains an active release cadence, frequently adding new spinner designs. Its primary role is to serve as a data source for spinner animations, differentiating it from full-fledged terminal animation libraries like `ora`, which consume `cli-spinners`' data to render actual progress indicators. This design choice makes it highly flexible, as the underlying `spinners.json` file can be directly utilized in various environments and programming languages, with official ports existing for Python, Swift, Rust, Go, and Bash.

npm install cli-spinners
INSTALL
IMPORT
SIG · CLI-SPINNERS
C
cli-spinners
observabilityjavascriptv3.4.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cliSpinners
✓ import cliSpinners from 'cli-spinners';
✗ const cliSpinners = require('cli-spinners');
The default export is an object containing all spinner definitions. `require` is not supported since v3.0.0 (pure ESM).
randomSpinner
✓ import { randomSpinner } from 'cli-spinners';
✗ import cliSpinners, { randomSpinner } from 'cli-spinners';
randomSpinner is a named export. While the default can be imported alongside, it's unnecessary if only randomSpinner is needed.
Spinner
✓ import type { Spinner } from 'cli-spinners';
Type import for TypeScript users to define the structure of a spinner object (interval, frames).

Demonstrates how to import the default `cliSpinners` object and `randomSpinner`, retrieve spinner data, and provides a basic manual animation loop for illustrative purposes (though `ora` is recommended for actual terminal animation).

import cliSpinners, { randomSpinner, type Spinner } from 'cli-spinners'; import process from 'node:process'; // Get a specific spinner by name const dotsSpinner: Spinner = cliSpinners.dots; console.log('Using "dots" spinner (first frame):', dotsSpinner.frames[0]); // Get a random spinner programmatically const randSpinner: Spinner = randomSpinner(); console.log(`\nUsing a random spinner (first frame): ${randSpinner.frames[0]}...`); // Example of manually animating a spinner (ora is recommended for production use) let frameIndex = 0; const spinnerName = 'dots'; const spinner = cliSpinners[spinnerName as keyof typeof cliSpinners]; // Access dynamically with type assertion const interval = spinner.interval; const frames = spinner.frames; process.stdout.write(`\nAnimating "${spinnerName}": `); const timer = setInterval(() => { process.stdout.write('\r'); // Clear the current line process.stdout.write(`Animating "${spinnerName}": ${frames[frameIndex]}`); frameIndex = (frameIndex + 1) % frames.length; }, interval); // Stop the animation after a few seconds setTimeout(() => { clearInterval(timer); process.stdout.write('\r \r'); // Clear the spinner line completely console.log(`\nStopped animating "${spinnerName}".`); }, 3000);
Debug
Known issues
breakingThis package transitioned to pure ECMAScript Modules (ESM) in version 3.0.0. Attempting to use `require()` to import `cli-spinners` will result in an `ERR_REQUIRE_ESM` runtime error.
fix
Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extension) and use `import cliSpinners from 'cli-spinners';` for imports.
affects: >=3.0.0
breakingVersion 3.0.0 of `cli-spinners` raised the minimum Node.js requirement to 18.x. Running this package on older Node.js versions will lead to runtime errors or compatibility issues.
fix
Upgrade your Node.js environment to version 18.x or newer.
affects: >=3.0.0
gotcha`cli-spinners` provides only the raw data (frames and recommended intervals) for spinners. It does not include any logic for animating or displaying these spinners in the terminal. If you need a fully functional terminal spinner, you should use a higher-level library like `ora`.
fix
For actual animated spinners, install and use `ora` (e.g., `npm install ora`) which consumes `cli-spinners` internally. For custom animation, use `setInterval` and `process.stdout.write` with the spinner's frames and interval.
affects: >=1.0.0
gotchaSpinner frames use various Unicode characters. While most modern terminals and fonts support these, some older or non-standard terminal emulators might display characters incorrectly or as empty boxes, leading to broken animations.
fix
Test the chosen spinners in your target terminal environments. Consider offering a fallback or simpler spinner for environments with limited Unicode support, or advising users on suitable terminal fonts.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require()` `cli-spinners` in a CommonJS module after upgrading to v3.0.0.
fix
Refactor your code to use ES Modules (`import`) and ensure your project's `package.json` has `"type": "module"` or use `.mjs` file extensions.
TypeError: cliSpinners is not a function
Trying to invoke `cliSpinners` as a function or accessing properties on an undefined `cliSpinners` variable due to incorrect import.
fix
Ensure you are using the correct ESM import syntax: `import cliSpinners from 'cli-spinners';` and accessing properties like `cliSpinners.dots` (it's an object, not a function).
Cannot find module 'cli-spinners'
The package is not installed, or there is a typo in the import path/package name.
fix
Run `npm install cli-spinners` or `yarn add cli-spinners`. Double-check the spelling in your import statement.
Upgrade
Version history
3.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
1
Resources
cli-spinners — npm install cli-spinners · libregistry