# picospinner

> A lightweight, no dependency, pluggable CLI spinner library.

Latest version **3.1.2** (published 2026-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install picospinner
pnpm add picospinner
yarn add picospinner
bun add picospinner
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.2 |
| Published | 2026-07-29 |
| First published | 2024-07-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 26 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 95 |
| Author | PondWader |
| Maintainers | 43081j, pondwader |
| Keywords | spinner, cli, lightweight, minimal |

## Links

- npm: https://www.npmjs.com/package/picospinner
- Repository: https://github.com/tinylibs/picospinner
- Homepage: https://github.com/tinylibs/picospinner#readme
- Issues: https://github.com/tinylibs/picospinner/issues
- npm.io page: https://npm.io/package/picospinner

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 3.1.2 (latest) — 2026-07-29
- 3.0.0 — 2025-03-19
- 2.1.0 — 2025-03-16
- 2.0.0 — 2024-11-04
- 1.0.1 — 2024-07-02

## README

# picospinner

<img src="https://raw.githubusercontent.com/PondWader/picospinner/main/assets/demo.gif" width="522" alt="Demo">

A lightweight, no dependency, pluggable CLI spinner library.

## Install

```
npm i picospinner
```

#### ESM & CommonJS

As of version 3, this package is published exclusively as an [ES module](https://nodejs.org/api/esm.html#modules-ecmascript-modules). Recent Node.js versions (v20.17.0+) support [`require(esm)`](https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require) in [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules). If a version with CommonJS syntax is required version 2 of this package can be installed with `npm i picospinner@2`. Version 2 will continue to be maintained in the [v2](https://github.com/tinylibs/picospinner/tree/v2) branch for the foreseeable future but will not receive new features.

## Usage

### Basic

```js
import {Spinner} from 'picospinner';

const spinner = new Spinner('Loading...');
spinner.start();
setTimeout(() => {
  // Spinner can be ended with one of: succeed, fail, warn, info or stop
  spinner.succeed('Finished.');
}, 5000);
```

### Custom symbols

```js
import {Spinner} from 'picospinner';

const spinner = new Spinner('Loading...', {
  symbols: {
    warn: '⚠'
  }
});
spinner.start();
setTimeout(() => {
  spinner.warn("Something didn't go quite right.");
}, 5000);
```

### Custom frames

```js
import {Spinner} from 'picospinner';

const spinner = new Spinner('Loading...', {
  frames: ['-', '\\', '|', '/']
});
spinner.start();
setTimeout(() => {
  spinner.info('Finished.');
}, 5000);
```

### Removing the spinner

Calling `spinner.stop();` will stop the spinner and remove it.

### Output stream

Spinners write to `process.stdout` by default. To keep stdout available for machine-readable output, pass another stream such as `process.stderr`:

```js
import {Spinner} from 'picospinner';

const spinner = new Spinner({
  text: 'Loading...',
  stream: process.stderr
});
```

### Colours

As of version **3.0.0** colours are enabled by default. This feature uses the [`styleText`](https://nodejs.org/api/util.html#utilstyletextformat-text-options) function from [`node:util`](https://nodejs.org/api/util.html) if it is available (Node versions greater than **22.0.0**, **21.7.0** or **20.12.0**). If it's not available, no colours will be displayed.

The `colors` option can be passed to disable colours or customise the colours. The option accepts a boolean value controlling whether or not to display the default colours or it can be passed an object defining styles for each component type as shown below:

```js
// Create spinner with no colours
const spinner = new Spinner('Loading...', {colors: false});

// Create spinner with custom colours
const spinner = new Spinner('Loading...', {
  colors: {
    text: 'gray',
    succeed: ['bold', 'green'],
    spinner: 'magenta'
    // The other properties (fail, warn, info) will use the default colours since they're not specified in this example
  }
});
```

Alternatively, colours can be displayed by using a third-party formatter such as picocolors or chalk. First install picocolors:

```
npm i picocolors
```

Text can be formatted by passing pre-formatted text:

```js
import {Spinner} from 'picospinner';
import pc from 'picocolors';

const spinner = new Spinner(pc.blue('Loading...'));
spinner.start();
setTimeout(() => spinner.setText(pc.magenta("Now it's magenta!")), 1000);
```

Symbols can be formatted by passing a symbol formatter.

```js
import {Spinner} from 'picospinner';
import pc from 'picocolors';

const spinner = new Spinner({
  text: pc.blue('Loading...'),
  symbolFormatter: pc.green
});
spinner.start();
spinner.fail({
  text: 'Disaster!',
  symbolFormatter: pc.red
});
```

You can also use a formatter to add suffixes and prefixes:

```js
const spinner = new Spinner({
  ...opts,
  symbolFormatter: (str) => `Prefix ${str} Suffix`
});
```

### Custom rotation speed

A custom tick speed (how often the spinner rotates) in milliseconds can be passed to `spinner.start`:

```js
import {Spinner} from 'picospinner';

const spinner = new Spinner();
spinner.start(10);
```

---
_Source: https://npm.io/package/picospinner · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
