@hypernym/spinner

A tiny and super customizable CLI spinner for Node.

Repository ✦ Package ✦ Releases ✦ Discussions

pnpm add @hypernym/spinner

Features

• TypeScript friendly
• Fully tree-shakeable
• No dependencies

Usage

import { createSpinner } from '@hypernym/spinner'

const spinner = createSpinner()

spinner.start()

setTimeout(() => {
  spinner.update({
    message: 'Still loading...',
  })
}, 1000)

setTimeout(() => {
  spinner.update({
    message: 'Almost done...',
  })
}, 2000)

setTimeout(() => {
  spinner.stop()
}, 3000)

Methods

For all methods, each option is optional so you only need to specify what you want to change.

.start()

Starts the spinner.

import { createSpinner } from '@hypernym/spinner'

const spinner = createSpinner()

spinner.start({
  message: 'Loading module...',
})

.update()

Dynamically updates the spinner on the fly.

Very useful when you want to change the message or dynamics of other options before stopping the spinner.

import { createSpinner } from '@hypernym/spinner'

const spinner = createSpinner()

spinner.start()

setTimeout(() => {
  spinner.update({
    message: 'Still loading...',
  })
}, 1000)

setTimeout(() => {
  spinner.update({
    frames: ['-', '\\', '|', '/'],
    interval: 30,
    message: 'Almost done...',
  })
}, 2000)

.stop()

Stops the spinner with a custom mark and message.

Also, use this method as success, warning, cancel, error or similar events, since it is very customizable.

import { createSpinner } from '@hypernym/spinner'

const spinner = createSpinner()

spinner.start()

setTimeout(() => {
  spinner.stop({
    message: 'Module done!',
  })
}, 3000)

Options

It's possible to specify global options directly on the main spinner call. That way you don't have to define them for each method individually.

Also, all global options are optional.

frames

• Type: string[]
• Default: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']

Specifies the frames to be used in the spinner animation.

const spinner = createSpinner({
  frames: ['-', '\\', '|', '/'],
})

interval

• Type: number
• Default: 40

Specifies the time delay (in ms) between each frame.

const spinner = createSpinner({
  interval: 60,
})

template

• Type: function
• Default: undefined

Defines the line template.

Useful when you need to rearrange the position of the animation and message or change the template completely.

import { cyan } from '@hypernym/colors'

const spinner = createSpinner({
  template: (animation, message) => `${cyan(message)} ${cyan(animation)}`,
})

start

• Type: object
• Default: undefined

Specifies global options for the .start() method.

const spinner = createSpinner({
  start: {
    message: 'Loading module...',
  },
})

spinner.start()

stop

• Type: object
• Default: undefined

Specifies global options for the .stop() method.

import { cyan } from '@hypernym/colors'

const spinner = createSpinner({
  stop: {
    mark: cyan('✔'),
    message: 'Module done!',
    template: (mark, message) => `${message} ${mark}`,
  },
})

spinner.stop()

cancel

• Type: object
• Default: undefined

Specifies global options for the Node exit event.

It's activated when the user explicitly cancels the process in the terminal (ctrl + c).

import { magenta } from '@hypernym/colors'

const spinner = createSpinner({
  cancel: {
    mark: magenta('✖'),
    message: 'Module cancelled!',
    template: (mark, message) => `${message} ${mark}`,
  },
})

Community

Feel free to ask questions or share new ideas.

Use the official discussions to get involved.

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.