progressimo

A lightweight, animated, themeable CLI progress bar for Node.js.
Zero config to start — full customization when needed.

• 🎨 6 built-in themes — default, minimal, retro, blocks, dots, arrows
• ♿ Colorblind-friendly palettes — deuteranopia, protanopia, tritanopia
• 🎭 Custom JSON themes — load your own theme from a file
• ✨ Smooth animation — animated fill with configurable speed
• 📦 Tiny footprint — only 2 dependencies (chalk, cli-cursor)

Quick Start

npm install progressimo

import ProgressBar from 'progressimo';

// Zero config — works out of the box
const bar = new ProgressBar({ total: 100 });
bar.update(50);    // 50% done
bar.complete();    // jump to 100%, clean up

That's it — two lines to get a working progress bar.

Theme Previews

 default    [████████████████████░░░░░░░░░░] 60%

 minimal    [##################------------] 60%

 retro      [=================>------------] 60%

 blocks     [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░] 60%

 dots       [••••••••••••••••••············] 60%

 arrows     [▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▹▹▹▹▹▹▹▹▹▹▹▹] 60%

Usage Examples

With a Built-in Theme

import ProgressBar from 'progressimo';

const bar = new ProgressBar({ total: 100, theme: 'retro' });
bar.update(60);
// retro [===============>--------------] 60%

With a Colorblind Palette

const bar = new ProgressBar({
  total: 100,
  palette: 'deuteranopia',  // blue + orange — safe for red/green CVD
});
bar.update(75);

Fully Custom Config

const bar = new ProgressBar({
  total: 100,
  width: 40,
  label: 'Uploading',
  fill: '▰',
  empty: '▱',
  color: 'magentaBright',
});
bar.update(30);
// Uploading [▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱] 30%

Load a Custom JSON Theme

Create a JSON file like themes/my-theme.json:

{
  "fill": "★",
  "empty": "☆",
  "head": "",
  "leftBracket": "[",
  "rightBracket": "]",
  "color": "yellow"
}

Then use it:

const bar = new ProgressBar({
  total: 100,
  theme: './themes/my-theme.json',
});
bar.update(50);
// [★★★★★★★★★★★★★★★☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆] 50%

Smooth Animation

const bar = new ProgressBar({ total: 100, label: 'Installing' });

// The bar will smoothly slide from 0 → 80 instead of jumping
bar.update(80, { animate: true });

Using with Async Tasks

import ProgressBar from 'progressimo';

async function downloadFiles(files) {
  const bar = new ProgressBar({
    total: files.length,
    label: 'Downloading',
    theme: 'dots',
  });

  for (let i = 0; i < files.length; i++) {
    await downloadFile(files[i]);
    bar.update(i + 1);
  }
  bar.complete();
}

Increment Shortcut

const bar = new ProgressBar({ total: 200 });

bar.increment();     // 1/200
bar.increment(10);   // 11/200
bar.increment();     // 12/200
bar.complete();      // 200/200, done

Config Options

| Option | Type | Default | Description | |---|---|---|---| | total | number | 100 | Value that represents 100% | | theme | string | 'default' | Built-in theme name or path to a .json theme file | | palette | string | — | Colorblind palette: 'deuteranopia', 'protanopia', 'tritanopia' | | width | number | 30 | Character width of the bar (excluding brackets/label) | | label | string | '' | Text label before the bar | | fill | string | '█' | Fill character (overrides theme) | | empty | string | '░' | Empty character (overrides theme) | | head | string | '' | Leading edge character (overrides theme) | | color | string | 'cyan' | Chalk color name for the filled portion | | animationInterval | number | 50 | Milliseconds between frames during smooth animation | | stream | WriteStream | process.stderr | Output stream |

Built-in Themes

| Theme | Fill | Empty | Head | Color | |---|---|---|---|---| | default | █ | ░ | — | cyan | | minimal | # | - | — | white | | retro | = | - | > | green | | blocks | ▓ | ░ | — | magenta | | dots | • | · | — | yellow | | arrows | ▸ | ▹ | — | blue |

Colorblind Palettes

These palettes remap colors to combinations that are distinguishable for people with color vision deficiencies.

| Palette | Fill Color | Empty Color | Target | |---|---|---|---| | deuteranopia | blue | bright yellow | Reduced green sensitivity (most common) | | protanopia | bright blue | yellow | Reduced red sensitivity | | tritanopia | red | bright cyan | Reduced blue sensitivity |

API Reference

new ProgressBar(options?)

Create a new progress bar instance. All options are optional — zero config works out of the box.

.update(value, options?)

Set progress to an absolute value (clamped to 0–total).
Pass { animate: true } for smooth animation.

.increment(delta?)

Add delta (default 1) to the current progress.

.complete()

Jump to 100%, render the final frame, restore the cursor, and print a newline.

Advanced: Accessing Themes & Palettes

import { themes, palettes } from 'progressimo';

console.log(Object.keys(themes));
// ['default', 'minimal', 'retro', 'blocks', 'dots', 'arrows']

console.log(palettes.deuteranopia);
// { fill: 'blue', empty: 'yellowBright', label: 'white', percentage: 'blueBright' }

Demo

Run the interactive demo that cycles through all themes and palettes:

npx progressimo-demo
# or
node node_modules/progressimo/bin/demo.js

How It Works

The "animation" trick is simple: instead of printing new lines, we overwrite the same terminal line on every update.

1. readline.cursorTo(stream, 0) — moves the cursor back to column 0
2. readline.clearLine(stream, 0) — erases the current line
3. stream.write(barString) — writes the new bar

Because we never print a \n, the cursor stays on the same line. cli-cursor hides the blinking cursor during animation for a clean look.

Progress output goes to stderr by default so stdout stays clean for piping.

Publishing to npm

# Login to your npm account
npm login

# Publish (first time)
npm publish

# After making changes, bump the version
npm version patch   # 1.0.0 → 1.0.1
npm publish

Key concepts:

• "main" in package.json tells Node.js which file to load on import
• "bin" registers CLI commands (like progressimo-demo)
• "type": "module" enables ES Module syntax (import/export)
• "files" controls which files are included in the published tarball

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-theme)
3. Commit your changes (git commit -m 'Add new theme')
4. Push to the branch (git push origin feature/my-theme)
5. Open a Pull Request

License

MIT