cli-progress

You can customize the format string using built-in placeholders. These can be combined in any order.

Standard Placeholders:

• {bar}: The progress bar itself.
• {percentage}: Current progress in percent (0-100).
• {total}: The end value.
• {value}: The current value.
• {eta}: Expected time of accomplishment in seconds.
• {duration}: Elapsed time in seconds.
• {eta_formatted}: Expected time formatted into appropriate units.
• {duration_formatted}: Elapsed time formatted into appropriate units.
• {<payloadKeyName>}: The value of a custom token provided in the payload object during .start() or .update().

const opt = {
    format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}'
}
// Renders as: progress [========================================] 100% | ETA: 0s | 200/200

Single Bar Mode is used for a single progress bar in your terminal. You initialize it with new cliProgress.SingleBar(options, preset) and control it using .start(), .update(), and .stop().

const cliProgress = require('cli-progress');

// create a new progress bar instance and use shades_classic theme
const bar1 = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

// start the progress bar with a total value of 200 and start value of 0
bar1.start(200, 0);

// update the current value in your application..
bar1.update(100);

// stop the progress bar
bar1.stop();

Multi Bar Mode allows you to manage multiple progress bars simultaneously using a MultiBar container. You create the container, then use .create() to add individual bars. Each bar returned by .create() is a SingleBar instance that can be controlled independently.

const cliProgress = require('cli-progress');

// create new container
const multibar = new cliProgress.MultiBar({
    clearOnComplete: false,
    hideCursor: true,
    format: ' {bar} | {filename} | {value}/{total}',
}, cliProgress.Presets.shades_grey);

// add bars
const b1 = multibar.create(200, 0);
const b2 = multibar.create(1000, 0);

// control bars
b1.increment();
b2.update(20, {filename: "test1.txt"});
b1.update(20, {filename: "helloworld.txt"});

// stop all bars
multibar.stop();

Some examples in this repository use the ansi-colors library to provide terminal styling. This library is not a dependency of cli-progress itself, so you must install it manually if you wish to run those specific examples.

yarn install ansi-colors

You can install cli-progress using either yarn or npm.

$ yarn add cli-progress
$ npm install cli-progress --save

The MultiBar class manages a collection of progress bars.

Constructor new cliProgress.MultiBar(options:object [, preset:object])

Methods

• .create(totalValue:int, startValue:int [, payload:object = {} [, barOptions:object = {}]]): Adds and starts a new bar. Returns a SingleBar instance. barOptions can be used to override global settings for that specific bar (e.g., changing its format).
• .remove(barInstance:object): Removes a specific bar from the container.
• .stop(): Stops all active bars.
• .log(message:string): Outputs buffered content above the bars. Note: A newline \n is required at the end of the string.

The SingleBar class is used for individual progress bars.

Constructor new cliProgress.SingleBar(options:object [, preset:object])

Methods

• .start(totalValue:int, startValue:int [, payload:object = {}]): Starts the bar with a total and initial value. The payload allows you to pass custom data for tokens.
• .update([currentValue:int [, payload:object = {}]]): Sets the current value. To update only the payload without changing the progress value, set currentValue to null or pass only the payload.
• .increment([delta:int [, payload:object = {}]]): Increases the current value by delta (defaults to 1).
• .setTotal(totalValue:int): Updates the total value while the bar is active (useful for dynamic tasks).
• .stop(): Stops the bar and moves to the next line.
• .updateETA(): Forces a recalculation of the ETA.

When using SingleBar, you can listen to the following events:

• start: Triggered after start() is called.
• stop: Triggered after stop() is called.
• redraw-pre: Triggered before the current line is updated.
• redraw-post: Triggered after the current line is updated.

const cliProgress = require('cli-progress');
const bar1 = new cliProgress.SingleBar();

bar1.on('start', () => {
    console.log('bar started');
});