picospinner

3.0.0 verified Sat May 09 auth: no javascript

A lightweight, zero-dependency CLI spinner library for Node.js. Current stable version is 3.0.0, published as ESM-only (require() supported in Node >=20.17.0). Provides a simple Spinner class with start/stop/succeed/fail/warn/info methods, customizable frames and symbols, and built-in color support via node:util styleText (Node >=20.12.0). Unlike heavier alternatives like ora, picospinner has no dependencies and a minimal API. Version 2 remains maintained for CJS users. GitHub releases are infrequent; features are added conservatively.

Common errors

error TypeError: Spinner is not a constructor ↓

cause Using default import (import Spinner from 'picospinner') instead of named import.

fix

Use named import: import { Spinner } from 'picospinner'

error Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported. ↓

cause Using CommonJS require() with picospinner >=3.0.0 on Node <20.17.0.

fix

Switch to ESM: use import syntax, or install picospinner@2 for CommonJS support.

error SyntaxError: Cannot use import statement outside a module ↓

cause Using picospinner >=3.0.0 in a CommonJS module without enabling ESM.

fix

Set "type": "module" in package.json or use .mjs file extension.

Warnings

breaking In version 3, picospinner is ESM-only. CommonJS require() fails unless using Node.js >=20.17.0 with require(esm) enabled. ↓

fix If you must use CommonJS, install v2: `npm i picospinner@2`. For Node <20.17.0, ensure your project is ESM or use a dynamic import.

gotcha The `stop()` method ends the spinner without showing any symbol; use `succeed()`, `fail()`, `warn()`, or `info()` to display a completion symbol. ↓

fix Use `spinner.succeed('Done')` or another finishing method instead of `stop()` to show a completion indicator.

gotcha Color support depends on Node.js version. If Node <20.12.0, colors are silently disabled. No error or warning is emitted. ↓

fix Check `process.versions.node` and handle gracefully, or use a third-party color library like picocolors to ensure consistent coloring.

deprecated Version 2 is in maintenance mode and will not receive new features. Migrate to v3 when possible. ↓

fix Update to v3: `npm i picospinner@latest`, convert to ESM (use import instead of require).

Install

npm install picospinner

yarn add picospinner

pnpm add picospinner

Imports

Spinner
wrong
```
const Spinner = require('picospinner')
```
correct
```
import { Spinner } from 'picospinner'
```
Since v3, picospinner is ESM-only. In Node.js >=20.17.0, require(esm) works. For older Node or tools that don't support require(esm), install v2 with `npm i picospinner@2` and use `const { Spinner } = require('picospinner')`.
default import (Spinner class)
wrong
```
import Spinner from 'picospinner'
```
correct
```
import { Spinner } from 'picospinner'
```
picospinner exports only named exports. Default import will result in undefined at runtime.
type SpinnerOptions
```
import type { SpinnerOptions } from 'picospinner'
```
TypeScript types are shipped with the package. Use import type for type-only usage.

Quickstart

Shows instantiation, custom frames, symbols, colors, and the start/succeed pattern.

import { Spinner } from 'picospinner';

const spinner = new Spinner('Loading...', {
  frames: ['◰', '◳', '◲', '◱'],
  symbols: { succeed: '✓', fail: '✗' },
  colors: { text: 'cyan', spinner: 'yellow' }
});

spinner.start();

// Simulate async work
setTimeout(() => {
  spinner.succeed('Task completed!');
}, 3000);