node package manager


A live status bar generator for node.js


Makes a little stdout status bar. As simple or complex as you need.

npm install node-status

Example of custom patterns


Example of steps



var status = require('node-status')
var pizzas = status.addItem('pizza')


Status accepts the following config options on start():

  • invert: defaults to false. Inverts the colors of the bar.
  • interval: defaults to 250. Number of milliseconds per re-draw interval.
  • pattern: optional manual definition for status bar layout. See Patterns
    invert: true,
    interval: 200,
    pattern: 'Doing work: {uptime}  |  {spinner.cyan}  |  {}'

Item Options

All item options are optional.

option type default notes
count number 0 Can specify a starting count if needed.
max number null Will cause 'count' type to display as count/max. Required for some display types. Can be a number or a function that returns a number.
custom function null a function run when the pattern {<item>.custom} is used. Access this.count and this.max for values if needed. Must return a string.
precision number 2 The precision used in percentages.
steps Array false An array of strings that identify steps for the item. The count of the item identifies the current step.

Item Methods

method notes
inc( Number ) Increases the count on the item by the desired amount. If no amount is specified, will increase by 1.
dec( Number ) Decreases the count on the item by the desired amount. If no amount is specified, will decrease by 1.
doneStep( success:Boolean, message:String ) A helper method for when using steps on an item. Will stamp the step to the screen with a ✔ when success is true, ✖ when false. An optional message can be added which will be appended to the display. See the gif above, or the examples/steps.js


The pattern setting in status config can be used to layout your bar as you see fit, if the default doesn't suit you. Simply a string of tokens.

The pattern:

'Doing work: {uptime}  |  {spinner.cyan}  |  {}'

Would render as:

Doing work: 10s  |  ⠼  |  [▒▒▒▒▒▒----]

Tokens are specified as: {<token>[.color][.modifier]}.

All tokens support colorization with marak/colors.

Non-item tokens

token modifiers notes
uptime renders the current uptime of the process.
spinner spinner types renders a spinner. Any type available in cli-spinners can be used. Ex: {spinner.bouncingBall.cyan}

Item tokens

All items use their name as tokens. If you add an item named pizza, you can render it in the pattern with {pizza}. Simple.

Item type modifiers

The items have a number of types available to render.

type example
default 5 or 5/10 With no type specified, item is rendered as the count, or the count/max if max was specified.
percentage 15.23% Renders a simple percentage, requires max to be set. Uses the precision setting to round the value.
custom anything Renders whatever is returned by the specified custom function.
bar [▒▒▒▒▒-----] Renders as a progress bar. Requires max to be set.
time 15s Uses the count as milliseconds and renders the value as a nicely formatted time.

Using Console.log alongside status

Right now, if you have to use console.log after the status bar has started, it can be a bit janky because the stdout line isn't cleared when a console.log is run.

You can utilize an extended console.log by adding this after requiring status.

console = status.console()