Spinner

!version
!build

Asynchronous CLI Spinner. This package has been created to handle simultaneous/multiple spinner at a time. The package has been inspired by Ora but asynchronous.

All available spinners are part of cli-spinners package.

Requirements

- Node.js v22 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

``bash
$ npm i @topcli/spinner

or

$ yarn add @topcli/spinner
`

Usage example

Create and wait multiple spinner at a time.

`js
import * as timers from "node:timers/promises";
import { Spinner } from "@topcli/spinner";

async function fnWithSpinner(withPrefix, succeed = true) {
const spinner = new Spinner()
.start("Start working!", { withPrefix });

await timers.setTimeout(1000);
spinner.text = "Work in progress...";
await timers.setTimeout(1000);

if (succeed) {
spinner.succeed(All done in ${spinner.elapsedTime.toFixed(2)}ms !);
}
else {
spinner.failed("Something wrong happened !");
}
}

await Promise.allSettled([
fnWithSpinner(),
fnWithSpinner("Item 1"),
fnWithSpinner("Item 2", false)
]);
Spinner.reset(); // reset internal count
console.log("All spinners finished!");
`

If you want to only achieve one Spinner by one Spinner, use it like Ora (it will work)
`js
const spinner = new Spinner().start("Start working!");

await timers.setTimeout(1_000);
spinner.text = "Work in progress...";

await timers.setTimeout(1_000);
spinner.succeed("All done !");
`

> [!TIP]
> When you are working on a CLI that can be used as an API too, the verbose option allow you to disable the Spinner.

API

constructor(options?: SpinnerOptions)

Create a new Spinner. The options payload is described by the following TypeScript interface:

`ts
export interface SpinnerOptions {
/**
* Spinner name (from cli-spinners lib)
*
* @default "dots"
*/
name?: cliSpinners.SpinnerName;
/**
* Spinner frame color
*
* @default "white"
*/
color?: string;
/**
* Do not log anything when disabled
*
* @default true
*/
verbose?: boolean;
}
`

> [!TIP]
> Check cli-spinners for all the spinner name.

`js
new Spinner({ name: "dots2" });
`







start(text?: string, options?: StartOptions): Spinner

Start the spinner and optionaly write the text passed as first parameter.

The options payload is described by the following TypeScript interface:

`ts
export interface StartOptions {
withPrefix?: string;
}
``

succeed(text?: string): void

Stop the spinner in the CLI, write the text passed in param and mark it as succeed with a symbol.

failed(text?: string): void

Stop the spinner in the CLI, write the text passed in param and mark it as failed with a symbol.

Contributors ✨



Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 📖 👀 🛡️ 🐛

Alexandre Malaj 💻 📖 🐛

PierreDemailly 💻 🚧

Ben 🐛

License

MIT