Elegant CLI Spinner Frames

3.0.0 · maintenance · verified Wed Apr 22

elegant-spinner provides a simple, elegant set of ASCII frames designed for creating visual loading indicators in interactive command-line interface (CLI) applications. The current stable version is 3.0.0. This package itself does not handle the animation logic; rather, it supplies the individual spinner frames that an external utility (like `log-update` or `ora`) can iterate through to create an animated effect. Its release cadence is tied to Node.js compatibility updates and essential maintenance, rather than rapid feature development. A key differentiator is its minimalism, focusing solely on the spinner frames. However, for most use cases requiring a full-fledged animated spinner, the `ora` package is recommended as it bundles `elegant-spinner` and manages the animation loop automatically. It supports modern Node.js environments and is pure ESM since version 3.0.0, with TypeScript definitions available since version 2.0.0.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `elegant-spinner` using CommonJS `require()` syntax in a Node.js environment with version 3.0.0 or later.

fix Change your import statement from `const elegantSpinner = require('elegant-spinner');` to `import elegantSpinner from 'elegant-spinner';` and ensure your project is configured for ES modules (e.g., `"type": "module"` in package.json).

Warnings

breaking Version 3.0.0 and above is pure ESM (ECMAScript Modules). CommonJS `require()` statements are no longer supported and will result in an error.
Fix: Migrate your project to use ES modules (`import`/`export`) or use an older version of the package if CommonJS is strictly required.
breaking Version 3.0.0 requires Node.js 12.20.0, 14.13.1, or >=16.0.0. Older Node.js versions are not supported.
Fix: Upgrade your Node.js runtime to a compatible version.
gotcha This package only provides the spinner frames. It does not handle the animation logic (e.g., setting intervals, clearing output). For a complete, animated spinner solution, the `ora` package is generally recommended as it wraps `elegant-spinner` and handles animation automatically.
Fix: For full animation, consider using `ora`. If sticking with `elegant-spinner`, you'll need to manually implement the animation loop using tools like `log-update` and `setInterval`.
breaking Version 2.0.0 required Node.js 8 or higher. Prior versions supported older Node.js environments.
Fix: Ensure your Node.js version meets the requirement for the specific `elegant-spinner` version you are using. For versions 2.x, Node.js 8+ is needed.

Install

npm install elegant-spinner npm
yarn add elegant-spinner yarn
pnpm add elegant-spinner pnpm

Imports

elegantSpinner
wrong:
```
const elegantSpinner = require('elegant-spinner');
```
correct:
```
import elegantSpinner from 'elegant-spinner';
```
Since v3.0.0, this package is pure ESM and must be imported using ES modules syntax. CommonJS `require()` will fail.
FrameIterator
```
import elegantSpinner from 'elegant-spinner';
const frame = elegantSpinner();
// frame() returns the next string frame
```
The default import is a factory function that returns an iterator for spinner frames. Call it to get the next frame string.

Quickstart

Demonstrates how to import the `elegantSpinner` function and use it with `log-update` to render a basic animated spinner in the terminal, manually updating frames every 50ms and showing a progress percentage.

import elegantSpinner from 'elegant-spinner';
import logUpdate from 'log-update';

const spinnerFrames = elegantSpinner();
let counter = 0;
const interval = setInterval(() => {
  const currentFrame = spinnerFrames();
  logUpdate(`Loading ${currentFrame} ${counter++}%`);
  if (counter > 100) {
    clearInterval(interval);
    logUpdate.done();
    console.log('Loading complete!');
  }
}, 50);

view raw JSON →