nanospinner

To use Nano Spinner, import createSpinner from nanospinner. You can initialize a spinner with a text label and immediately start the animation. Use the .success() method to stop the animation and show a completion mark after your task is finished.

import { createSpinner } from 'nanospinner'

const spinner = createSpinner('Run test').start()

setTimeout(() => {
  spinner.success()
}, 1000)

The createSpinner function is the entry point for creating a new spinner instance. It is designed to be lightweight and supports both ESM and CJS projects with built-in TypeScript definitions.

import { createSpinner } from 'nanospinner'
const spinner = createSpinner('Initial text')

The .spin() method performs a single animation frame. To create a continuous animation loop, you must call .spin() repeatedly (e.g., using setInterval).

setInterval(() => {
  spinner.spin()
}, 25)

Call .stop(options?) to finish the spinning animation and return to a new line. You can provide a final message or custom styling.

spinner.stop()
spinner.stop('Done!')
spinner.stop({ text: 'Done!', mark: ':O', color: 'magenta' })

These methods stop the spinning animation and replace the spinning symbol with a specific mark character to indicate the outcome of a task.

• .success(options?): Shows a check mark.
• .warn(options?): Shows a warning mark.
• .error(options?): Shows a cross character.
• .info(options?): Shows an info mark.

spinner.success('Successful!')
spinner.warn('Warning!')
spinner.error('Error!')
spinner.info('Info!')

Call .start(options?) to begin drawing the spinning animation in the terminal. You can pass a string directly or an options object.

spinner.start()
spinner.start('Start')
spinner.start({ text: 'Start', color: 'yellow' })

Use .clear() to remove the spinner's output from the terminal, or .reset() to return the spinner to its initial frame.

spinner.clear()
spinner.reset()

Use .update(options?) to change the spinner's properties while it is running. You can update the text, color, output stream, animation frames, or the animation interval.

spinner.update({
  text: 'Run test',
  color: 'white',
  stream: process.stdout,
  frames: ['.', 'o', '0', '@', '*'],
  interval: 100,
})

The Spinner interface provides methods to manage the animation state and terminal output:

• start(opts?): Begins the animation. opts can be a string or an object { text?: string; color?: Color }.
• stop(opts?): Stops the animation. opts can be a string or an object { text?: string; mark?: string; color?: Color; update?: boolean }.
• update(opts): Updates the spinner's configuration (text, frames, interval, or color). Accepts a string or an Options object.
• reset(): Resets the spinner state (current frame, lines, spinning status) and clears timers.
• clear(): Clears the lines previously written by the spinner in the terminal.
• isSpinning(): Returns a boolean indicating if the spinner is currently active.

const spinner = createSpinner('Working...');

spinner.start();
// ... do work
spinner.update('Almost done...');
// ... do work
spinner.stop();

Use createSpinner(text, opts) to initialize a new terminal animation instance. You can provide an initial text string and an optional Options object to configure the behavior.

Options:

• stream: A NodeJS.WriteStream to write to (defaults to process.stderr).
• frames: An array of strings representing the animation frames.
• interval: The delay between frames in milliseconds (defaults to 50).
• text: The initial text displayed next to the spinner.
• color: A color name (compatible with picocolors) for the spinner frame (defaults to 'yellow').

import { createSpinner } from 'nanospinner';

const spinner = createSpinner('Loading...', { interval: 100, color: 'cyan' });