spinnies

Spinnies

Node.js module to create and manage multiple spinners in command-line interface programs

Installation

$ npm i spinnies

Usage & Example

const spinnies = new Spinnies();

spinnies.add('spinner-1', { text: 'I am a spinner' });
spinnies.add('spinner-2', { text: 'I am another spinner' });

setTimeout(() => {
  spinnies.succeed('spinner-1', { text: 'Success!' });
  spinnies.fail('spinner-2', { text: 'Fail :(' });
}, 2000);

API

This library follows the a non-error-throwing philosophy. If you provide an invalid option or an invalid value for a valid option it will be ignored.

Initialization:

new Spinnies([options])

Parameters

• options - object:
  • color - string: Any valid chalk color. Default value is white.
  • succeedColor - string: Any valid chalk color. Default value is green.
  • failColor - string: Any valid chalk color. Default value is red.
  • spinnerColor- string: Any valid chalk color. Default value is greenBright.
  • spinner- object:
    • interval - number
    • frames - string[]
    You can see the already provided spinner here.
  • disableSpins - boolean: Disable spins (will still print raw messages).

Note: If you are working in any win32 platform, the default spin animation will be overriden. You can get rid of this defining a different spinner animation manually.

Example:

const spinner = { interval: 80, frames: ['🍇', '🍈', '🍉', '🍋'] }
const spinnies = new Spinnies({ color: 'blue', succeedColor: 'green', spinner });

Instance methods:

add(name, [options])

Adds a new spinner with the given name.

Parameters:

• name - string: spinner reference name.
• options - object:
  • text: - string: Optional text to show in the spinner. If none is provided, the name field will be shown.
  • status - string: Initial status of the spinner. Valid statuses are: succeed, fail, spinning, non-spinnableand stopped.
  • color - string: Any valid chalk color.
  • succeedColor - string: Any valid chalk color.
  • failColor - string: Any valid chalk color.

Return value: Returns the spinner's options.

Example:

const spinnies = new Spinnies();
spinnies.add('spinner-1');
spinnies.add('another-spinner', { text: 'Hello, I am a spinner!', color: 'greenBright' });

pick(name)

Picks a spinner.

Parameters:

• name - string: spinner reference name.

Return value: Returns the spinner's options.

update(name, [options])

Updates the spinner with name name with the provided options.

Parameters:

• name - string: spinner reference name.
• options - object:
  • text: - string: Optional text to show in the spinner. If none is provided, the name field will be shown.
  • status - string: New status of the spinner. Valid statuses are: succeed, fail, spinning, non-spinnableand stopped.
  • color - string: Any valid chalk color.
  • succeedColor - string: Any valid chalk color.
  • failColor - string: Any valid chalk color.

Return value: Returns the spinner's options.

Example:

const spinnies = new Spinnies();
spinnies.add('spinner-1', { text: 'Hello! I am the initial text', color: 'green' });
// some code
spinnies.update('spinner-1', { text: 'Hello, I am an updated text!', color: 'blue' });

succeed(name, [options])

Sets the specified spinner status as succeed.

Parameters:

• name - string: spinner reference name.
• options - object:
  • text: - string: Optional text to show in the spinner. If none is provided, the name field will be shown.
  • succeedColor - string: Any valid chalk color.

Return value: Returns the spinner's options.

Example:

const spinnies = new Spinnies();
spinnies.add('spinner-1', { text: 'Hello! I am the initial text', color: 'green' });
// some code
spinnies.succeed('spinner-1', { text: 'Success!', successColor: 'greenBright' });

fail(name, [options])

Sets the specified spinner status as fail.

Parameters:

• name - string: spinner reference name.
• options - object:
  • text: - string: Optional text to show in the spinner. If none is provided, the name field will be shown.
  • failColor - string: Any valid chalk color.

Return value: Returns the spinner's options.

Example:

const spinnies = new Spinnies();
spinnies.add('spinner-1', { text: 'Hello! I am the initial text', color: 'green' });
// some code
spinnies.fail('spinner-1', { text: 'I failed', failColor: 'redBright' });

stopAll([status])

Stops the spinners and sets the non-succeeded and non-failed ones to the provided status, which can be succeed, fail or stopped. You can see an example here.

hasActiveSpinners()

Return value: returns false if all spinners have succeeded, failed or have been stopped.

Contribute

Star it, fork it, improve it, PR it! :raised_hands:.

Acknowledgements

Thanks to chalk for helping making this lib colorful :rainbow: and to ora which was a great inspiration :unicorn:.

License

MIT

Changelog

[0.4.0] - 2019-06-16

Fixed

• Fix Windows default spinner and prefix (#8). Thanks @RedDuckss!
• Strip ANSI escape codes before cleaning the stream (https://github.com/jcarpanelli/spinnies/commit/574a1eb5a370c05e70d8d03ecf73e5292353468d)

Added

• Add succeedPrefix and failPrefix (#8). Thanks @RedDuckss!

Changed

• Set terminal color as default text color, and avoid using chalk.white (https://github.com/jcarpanelli/spinnies/commit/2da89d852fc6a89bb06715cccba94ccd632b4430)

Removed

• Remove default non-spinnable text prefix (https://github.com/jcarpanelli/spinnies/commit/38e6637f79fbc3712889ee6cc59f94cd91d1da1e)