Progress BarUsage Guide
Usage Guide
Complete API reference for ProgressBar and MultiProgressBar
ProgressBar
Constructor
import { ProgressBar } from '@visulima/progress-bar';
const bar = new ProgressBar(options, interactiveManager?, payload?);Options
| Option | Type | Default | Description |
|---|---|---|---|
total | number | required | Total value for 100% |
current | number | 0 | Starting value |
width | number | 40 | Bar width in characters |
format | string | "progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}" | Output format template |
style | ProgressBarStyle | "shades_classic" | Bar character style |
barCompleteChar | string | string[] | Style default | Complete portion character(s) |
barIncompleteChar | string | string[] | Style default | Incomplete portion character(s) |
barGlue | string | "" | Separator between complete/incomplete |
fps | number | 10 | Max frames per second |
peak | number | — | Peak marker position |
peakChar | string | Complete char | Character for peak marker |
roundedCaps | boolean | true for braille | Pill-shaped bar ends |
Methods
update(current, payload?)
Update the progress value.
bar.update(50);
bar.update(75, { speed: "2.5 MB/s" });increment(step?, payload?)
Increment by a step value (default: 1).
bar.increment(); // +1
bar.increment(10); // +10
bar.increment(5, { file: "data.json" });render()
Render the progress bar as a string.
const output = bar.render();
console.log(output);start(total?, startValue?, payload?)
Start the progress bar (hooks into interactive manager if provided).
bar.start();
bar.start(200); // Override total
bar.start(200, 50); // Override total and start valuestop()
Stop the progress bar and unhook from interactive manager.
bar.stop();setPeak(peak)
Set the peak marker position.
bar.setPeak(75); // Show peak at 75%Format Placeholders
| Placeholder | Description |
|---|---|
{bar} | The progress bar characters |
{percentage} | Current percentage (0-100) |
{value} | Current value |
{total} | Total value |
{eta} | Estimated time remaining in seconds |
{custom} | Any key from the payload object |
const bar = new ProgressBar(
{
total: 100,
format: "{task} [{bar}] {percentage}% | {speed}",
},
undefined,
{ task: "Upload", speed: "0 KB/s" },
);
bar.update(50, { speed: "1.2 MB/s" });MultiProgressBar
Display multiple progress bars simultaneously.
Constructor
import { MultiProgressBar } from '@visulima/progress-bar';
const multi = new MultiProgressBar(options?, interactiveManager?);Options
| Option | Type | Default | Description |
|---|---|---|---|
format | string | Default format | Format for all bars |
style | ProgressBarStyle | "shades_classic" | Style for all bars |
barCompleteChar | string | string[] | Style default | Complete char |
barIncompleteChar | string | string[] | Style default | Incomplete char |
barGlue | string | "" | Bar separator |
fps | number | 10 | Max FPS |
composite | boolean | false | Overlay bars in one line |
Methods
create(total, current?, payload?)
Create a new progress bar within the multi-bar manager.
const bar1 = multi.create(100);
const bar2 = multi.create(200, 50);
const bar3 = multi.create(150, 0, { task: "Build" });remove(bar)
Remove a progress bar from the manager.
multi.remove(bar1);stop()
Stop all progress bars.
multi.stop();setBarColor(bar, color)
Set a color function for a specific bar.
multi.setBarColor(bar1, (text) => `\x1b[32m${text}\x1b[0m`);Composite Mode
Overlay multiple bars in a single line:
const multi = new MultiProgressBar({ composite: true }, manager);
const download = multi.create(100);
const extract = multi.create(100);
download.update(80);
extract.update(40);
// Renders as a single composite bar showing both progress valuesUtility Functions
getBarChar(char, style, complete?)
Get the appropriate bar character for a style.
import { getBarChar } from "@visulima/progress-bar";
getBarChar(undefined, "ascii", true); // '#'
getBarChar(undefined, "ascii", false); // '-'
getBarChar(undefined, "braille", true); // '⣿'
getBarChar("X", "ascii"); // 'X' (custom override)applyStyleToOptions(options)
Apply style defaults to options, allowing overrides.
import { applyStyleToOptions } from "@visulima/progress-bar";
const opts = applyStyleToOptions({ total: 100, style: "braille" });
// opts.barCompleteChar === '⣿'
// opts.barIncompleteChar === '⠤'