# xprogress

> Dynamic, Flexible, extensible progressive CLI bar for the terminal built with NodeJS

Latest version **0.21.0** (published 2026-03-25) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install xprogress
pnpm add xprogress
yarn add xprogress
bun add xprogress
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.21.0 |
| Published | 2026-03-25 |
| First published | 2019-03-29 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=12 |
| Dependencies | 8 |
| Unpacked size | 64.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Miraculous Owonubi |
| Maintainers | miraclx |
| Keywords | bar, cli, ascii, progress, progressbar, stream, speed, bytes, monitor, percentage, loader, pulsate |

## Links

- npm: https://www.npmjs.com/package/xprogress
- Repository: https://github.com/miraclx/xprogress
- Homepage: https://github.com/miraclx/xprogress#readme
- Issues: https://github.com/miraclx/xprogress/issues
- npm.io page: https://npm.io/package/xprogress

## Dependencies (8)

- [xbytes](https://npm.io/package/xbytes.md) ^1.6.1
- [stringd](https://npm.io/package/stringd.md) ^2.2.0
- [pad-ratio](https://npm.io/package/pad-ratio.md) ^2.0.0
- [pretty-ms](https://npm.io/package/pretty-ms.md) ^5.1.0
- [speedometer](https://npm.io/package/speedometer.md) ^1.1.0
- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2
- [stringd-colors](https://npm.io/package/stringd-colors.md) ^1.11.0
- [progress-stream](https://npm.io/package/progress-stream.md) ^2.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.21.0 (latest) — 2026-03-25
- 0.20.0 — 2023-06-20
- 0.19.2 — 2023-06-20
- 0.19.1 — 2022-07-06
- 0.19.0 — 2022-07-06
- 0.18.0 — 2022-06-23
- 0.17.3 — 2020-07-15
- 0.17.2 — 2020-07-02
- 0.17.1 — 2020-04-21
- 0.17.0 — 2020-04-21
- 0.15.1 — 2020-01-27
- 0.13.0 — 2020-01-18
- 0.12.1 — 2020-01-10
- 0.12.0 — 2020-01-09
- 0.11.0 — 2020-01-09
- … 10 more at https://npm.io/package/xprogress/versions

## README

# xprogress

> Construct Dynamic, Flexible, extensible progressive CLI bar for the terminal built with NodeJS

## DOCUMENTATION INCOMPLETE

## Features

- Stream management functionality

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]

[![NPM][npm-image-url]][npm-url]

## Installing

Via [NPM][npm]:

``` bash
npm install xprogress
```

## Usage

Create a basic progress bar that updates itself with 10% twice every second until it's at maximum

``` javascript
import ProgressBar from 'xprogress';

const ProgressBar = require('xprogress');

const bar = new ProgressBar(100);

const interval = setInterval(() => {
  bar.tick(10).draw();
  if (bar.isComplete()) {
    bar.end(`The bar completed\n`);
    clearInterval(interval);
  }
}, 500);
```

![XProgress Example Result][xprogress-result]

## How It Works

ProgressBar uses [stringd][] to parse content within [`ProgressBar::template`](#progressbar:template) with variables in [`ProgressBar::variables`](#progressbar:variables) and then displays them on the terminal.
This sequence occurs for every time [`ProgressBar::draw()`](#progressbar:draw) is called.

## API

### <a id="progressbar"></a> new `ProgressBar`(total[, slots][, opts])

- `total`: &lt;[number][]&gt;
- `slots`: &lt;[HybridInput](#hybridinput)[]&gt;
- `opts`: &lt;[BarOpts][]&gt;

Create and return an xprogress instance
`slots` define the percentage to each part of the progressbar. This is parsed by [pad-ratio][] to a max of 100.

``` javascript
const bar = new ProgressBar(100, [20, 44]);
```

### <a id="globopts"></a> `GlobOpts`: [Object][object]

- `bar`: [Object][object]
  - `blank`: &lt;[string][]&gt; Content to use for the blank portion of the progressbar. **Default**: `'-'`.
  - `filler`: &lt;[string][]&gt; Content to use for the filled portion of the progressbar. **Default**: `'#'`.
  - `header`: &lt;[string][]&gt; Content to use for the header(s) of progressbars. **Default**: `''`.
  - `colorize`: &lt;[boolean][]&gt; Whether or not to allow colors in the bar. **Default**: `true`.
  - `separator`: &lt;[string][]&gt; Content to use when separating bars. **Default**: `''`.
  - `pulsateSkip`: &lt;[number][]&gt; Distance away at which to skip a pulsating bar. **Default**: `15`.
  - `pulsateLength`: &lt;[number][]&gt; The length of a pulsating progressbar. **Default**: `15`.
- `clean`: &lt;[boolean][]&gt; Whether or not to clear the progressbar buffer on the terminal after [`ProgressBar::end()`](#progress:end) has been called. **Default**: `false`.
- `flipper`: &lt;[string][]|[string][][]&gt; Content(s) to use for the progressbar flipper. This would cycle through all indexes in this property for everywhere :{flipper} is speified. **Default**: `['|', '/', '-', '\']`.
- `pulsate`: &lt;[boolean][]&gt; Whether or not to use a pulsate view for the progressbar. **Default**: `false`.
- <a id="globopts:template"></a> `template`: &lt;[string][]|[string][][]&gt; The template to use for the progressbar view. This is parsed by [stringd][]. with [`this.variables`](#globopts:variables) **Default**: `''`.
- <a id="globopts:variables"></a> `variables`: &lt;[VariableOpts](#variableopts)&gt; Variables with which to parse [`this.template`](#globopts:template), extended with [`cStringd.raw`][cstringd:raw].
- `forceFirst`: &lt;[boolean][]&gt; Whether or not to force a multi-bar progressbar to a single bar (useful either when terminal width is too small or when filled with excess addons). **Default**: `false`.
- `writeStream`: &lt;[WriteStream][]&gt; The tty-ish writable stream we are writing to. **Default**: [stdout](https://nodejs.org/api/process.html#processstdout).

The global options shared by both [ProgressBar](#progressbar) and [ProgressStream](#progressstream).

### <a id="variableopts"></a> `VariableOpts` <sub>extends [`cStringd.raw`][cStringd:raw]</sub>: [`Object`][object]

- `tag`: &lt;any&gt; Floating mutable tag to be attached to the bar
- *`bar`: &lt;[string]&gt; The progress bar itself
- *`label`: &lt;any&gt; The label to be attached to the bar
- *`total`: &lt;any&gt; The maximum value for the entire duration of the bar
- `flipper`: &lt;any&gt; The flipper as defined in the definition for the progressbar. **Default**: `['|', '/', '-', '\']`.
- *`completed`: &lt;any&gt; The value for the completion level of the entire bar activity. Generated from [`ProgressBar::average()`](#progressbar:average).`completed`
- *`remaining`: &lt;any&gt;
- *`percentage`: &lt;any&gt;

Variables with which to parse [`this.template`](#globopts:template), extended with [`cStringd.raw`][cstringd:raw]. variables prepended with `*` will be ignored anywhere else besides wherever's explicitly requesting a drawn bar.

### <a id="streamvariables"></a> `StreamVariables` <sub>extends [`VariableOpts`](#variableopts)</sub>: [`Object`][object]

- `eta`: &lt;[string]&gt; Duration for the entire progress to end. Parsed by [prettyMs]
- `size`: &lt;[ByteString]&gt; Human readable size for the number of total transferred bytes. Parsed by [xbytes]
- `speed`: &lt;[string]&gt; Human readable speed for the number of bits transferred per second. Parsed by [xbytes]
- `progress`: &lt;[ProgressStreamSlice]&gt; The Progress Object
- `eta:raw`: &lt;[number]&gt; Duration estimate of how long it would take for the stream to end based on the number of bytes being steadily transmitted per second.
- `slot:bar`: &lt;[string]&gt; The bar for the active chunk of the progressbar.
- `slot:blank`: &lt;[string]&gt; The character with which to be used as the slot's blank character.
- `slot:eta`: &lt;[string]&gt; Duration estimate for the active chunk to be completed. Parsed by [prettyMs]
- `slot:eta:raw`: &lt;[number]&gt; Duration estimate for the active chunk to be completed.
- `slot:filler`: &lt;[string]|[string][][]&gt; The character(s) with which to be used as the slot's filler character.
- `slot:header`: &lt;[string]&gt; The character with which to be used as the slot's header character.
- `slot:size`: &lt;[ByteString]&gt; Human readable size for the number of transferred bytes specific for the active chunk. Parsed by [xbytes]
- `slot:total`: &lt;[ByteString]&gt; Human readable size for the total number of bytes that can be processed by the active chunk. Parsed by [xbytes]
- `slot:runtime`: &lt;[string]&gt; Runtime for the active chunk. Parsed by [prettyMs]
- `slot:runtime:raw`: &lt;[number]&gt; Runtime for the active chunk.
- `slot:percentage`: &lt;[string]&gt; Integer defining the active slot completion percentage
- `slot:size:total`: &lt;[ByteString]&gt; Human readable size for the total number of bytes transferred in a single instance

### <a id='hybridinput'></a> `HybridInput`: [string][]|[number][]|[number][][]

This content here is parsed by [pad-ratio][] in the construct of an [HybridInput][hybridinput].

## Development

### Building

Feel free to clone, use in adherance to the [license](#license). Pull requests are very much welcome.

``` bash
git clone https://github.com/miraclx/xprogress.git
cd xprogress
npm install
# hack on code
```

## License

[Apache 2.0][license] © **Miraculous Owonubi** ([@miraclx][author-url]) &lt;<omiraculous@gmail.com>&gt;

[BarOpts]: #globopts

[npm]:  https://github.com/npm/cli "The Node Package Manager"
[license]:  LICENSE "Apache 2.0 License"

[stringd]:  https://github.com/miraclx/stringd "NodeJS String Variable Parser"
[xbytes]:  https://github.com/miraclx/xbytes "NodeJS ByteParser"
[prettyMs]:  https://github.com/sindresorhus/pretty-ms "Convert milliseconds to a human readable string: `1337000000` → `15d 11h 23m 20s`"
[pad-ratio]:  https://github.com/miraclx/pad-ratio "Pad or trim an array to sum up to a maximum value"
[hybridinput]:  https://github.com/miraclx/pad-ratio#hybridinput
[ProgressStreamSlice]: https://github.com/freeall/progress-stream#progress
[ByteString]: https://github.com/miraclx/xbytes#bytestring
[cstringd:raw]:  https://github.com/miraclx/stringd-colors#cstringdraw "Raw ANSI codes for stringd-colors"

[author-url]: https://github.com/miraclx
[xprogress-result]: screenshots/example.gif "StringD Colors Example"

[npm-url]: https://npmjs.org/package/xprogress
[npm-image]: https://badgen.net/npm/node/xprogress
[npm-image-url]: https://nodei.co/npm/xprogress.png?stars&downloads
[downloads-url]: https://npmjs.org/package/xprogress
[downloads-image]: https://badgen.net/npm/dm/xprogress

[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type

[WriteStream]: https://nodejs.org/api/tty.html#class-ttywritestream

---
_Source: https://npm.io/package/xprogress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._