{"id":16967,"library":"cli-spinners","title":"CLI Spinners","description":"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.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/sindresorhus/cli-spinners","tags":["javascript","cli","spinner","spinners","terminal","term","console","ascii","unicode","typescript"],"install":[{"cmd":"npm install cli-spinners","lang":"bash","label":"npm"},{"cmd":"yarn add cli-spinners","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-spinners","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export is an object containing all spinner definitions. `require` is not supported since v3.0.0 (pure ESM).","wrong":"const cliSpinners = require('cli-spinners');","symbol":"cliSpinners","correct":"import cliSpinners from 'cli-spinners';"},{"note":"randomSpinner is a named export. While the default can be imported alongside, it's unnecessary if only randomSpinner is needed.","wrong":"import cliSpinners, { randomSpinner } from 'cli-spinners';","symbol":"randomSpinner","correct":"import { randomSpinner } from 'cli-spinners';"},{"note":"Type import for TypeScript users to define the structure of a spinner object (interval, frames).","symbol":"Spinner","correct":"import type { Spinner } from 'cli-spinners';"}],"quickstart":{"code":"import cliSpinners, { randomSpinner, type Spinner } from 'cli-spinners';\nimport process from 'node:process';\n\n// Get a specific spinner by name\nconst dotsSpinner: Spinner = cliSpinners.dots;\nconsole.log('Using \"dots\" spinner (first frame):', dotsSpinner.frames[0]);\n\n// Get a random spinner programmatically\nconst randSpinner: Spinner = randomSpinner();\nconsole.log(`\\nUsing a random spinner (first frame): ${randSpinner.frames[0]}...`);\n\n// Example of manually animating a spinner (ora is recommended for production use)\nlet frameIndex = 0;\nconst spinnerName = 'dots';\nconst spinner = cliSpinners[spinnerName as keyof typeof cliSpinners]; // Access dynamically with type assertion\nconst interval = spinner.interval;\nconst frames = spinner.frames;\n\nprocess.stdout.write(`\\nAnimating \"${spinnerName}\": `);\n\nconst timer = setInterval(() => {\n    process.stdout.write('\\r'); // Clear the current line\n    process.stdout.write(`Animating \"${spinnerName}\": ${frames[frameIndex]}`);\n    frameIndex = (frameIndex + 1) % frames.length;\n}, interval);\n\n// Stop the animation after a few seconds\nsetTimeout(() => {\n    clearInterval(timer);\n    process.stdout.write('\\r                                  \\r'); // Clear the spinner line completely\n    console.log(`\\nStopped animating \"${spinnerName}\".`);\n}, 3000);\n","lang":"typescript","description":"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)."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to version 18.x or newer.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"`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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Spinner 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Refactor your code to use ES Modules (`import`) and ensure your project's `package.json` has `\"type\": \"module\"` or use `.mjs` file extensions.","cause":"Attempting to `require()` `cli-spinners` in a CommonJS module after upgrading to v3.0.0.","error":"ERR_REQUIRE_ESM"},{"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).","cause":"Trying to invoke `cliSpinners` as a function or accessing properties on an undefined `cliSpinners` variable due to incorrect import.","error":"TypeError: cliSpinners is not a function"},{"fix":"Run `npm install cli-spinners` or `yarn add cli-spinners`. Double-check the spelling in your import statement.","cause":"The package is not installed, or there is a typo in the import path/package name.","error":"Cannot find module 'cli-spinners'"}],"ecosystem":"npm","meta_description":null}