# progress

> Flexible ascii progress bar

Latest version **2.0.3** (published 2018-12-05) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 18/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2018-12-05 |
| First published | 2011-04-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/progress) |
| Module format | CommonJS |
| Node | >=0.4.0 |
| Dependencies | 0 |
| Unpacked size | 15.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2987 |
| Author | TJ Holowaychuk |
| Maintainers | prezjordan, thebigredgeek, thejameskyle, tjholowaychuk |
| Keywords | cli, progress |

## Links

- npm: https://www.npmjs.com/package/progress
- Repository: https://github.com/visionmedia/node-progress
- Homepage: https://github.com/visionmedia/node-progress#readme
- Issues: https://github.com/visionmedia/node-progress/issues
- npm.io page: https://npm.io/package/progress

## 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

- 2.0.3 (latest) — 2018-12-05
- 2.0.2 — 2018-12-03
- 2.0.1 — 2018-10-17
- 2.0.0 — 2017-04-04
- 1.1.8 — 2014-08-10
- 1.1.7 — 2014-07-01
- 1.1.6 — 2014-06-16
- 1.1.5 — 2014-03-25
- 1.1.4 — 2014-03-13
- 1.1.3 — 2013-12-31
- 1.1.2 — 2013-10-17
- 1.1.0 — 2013-09-18
- 1.0.1 — 2013-09-07
- 1.0.0 — 2013-06-19
- 0.1.0 — 2012-09-19
- … 5 more at https://npm.io/package/progress/versions

## README

Flexible ascii progress bar.

## Installation

```bash
$ npm install progress
```

## Usage

First we create a `ProgressBar`, giving it a format string
as well as the `total`, telling the progress bar when it will
be considered complete. After that all we need to do is `tick()` appropriately.

```javascript
var ProgressBar = require('progress');

var bar = new ProgressBar(':bar', { total: 10 });
var timer = setInterval(function () {
  bar.tick();
  if (bar.complete) {
    console.log('\ncomplete\n');
    clearInterval(timer);
  }
}, 100);
```

### Options

These are keys in the options object you can pass to the progress bar along with
`total` as seen in the example above.

- `curr` current completed index
- `total` total number of ticks to complete
- `width` the displayed width of the progress bar defaulting to total
- `stream` the output stream defaulting to stderr
- `head` head character defaulting to complete character
- `complete` completion character defaulting to "="
- `incomplete` incomplete character defaulting to "-"
- `renderThrottle` minimum time between updates in milliseconds defaulting to 16
- `clear` option to clear the bar on completion defaulting to false
- `callback` optional function to call when the progress bar completes

### Tokens

These are tokens you can use in the format of your progress bar.

- `:bar` the progress bar itself
- `:current` current tick number
- `:total` total ticks
- `:elapsed` time elapsed in seconds
- `:percent` completion percentage
- `:eta` estimated completion time in seconds
- `:rate` rate of ticks per second

### Custom Tokens

You can define custom tokens by adding a `{'name': value}` object parameter to your method (`tick()`, `update()`, etc.) calls.

```javascript
var bar = new ProgressBar(':current: :token1 :token2', { total: 3 })
bar.tick({
  'token1': "Hello",
  'token2': "World!\n"
})
bar.tick(2, {
  'token1': "Goodbye",
  'token2': "World!"
})
```
The above example would result in the output below.

```
1: Hello World!
3: Goodbye World!
```

## Examples

### Download

In our download example each tick has a variable influence, so we pass the chunk
length which adjusts the progress bar appropriately relative to the total
length.

```javascript
var ProgressBar = require('progress');
var https = require('https');

var req = https.request({
  host: 'download.github.com',
  port: 443,
  path: '/visionmedia-node-jscoverage-0d4608a.zip'
});

req.on('response', function(res){
  var len = parseInt(res.headers['content-length'], 10);

  console.log();
  var bar = new ProgressBar('  downloading [:bar] :rate/bps :percent :etas', {
    complete: '=',
    incomplete: ' ',
    width: 20,
    total: len
  });

  res.on('data', function (chunk) {
    bar.tick(chunk.length);
  });

  res.on('end', function () {
    console.log('\n');
  });
});

req.end();
```

The above example result in a progress bar like the one below.

```
downloading [=====             ] 39/bps 29% 3.7s
```

### Interrupt

To display a message during progress bar execution, use `interrupt()`
```javascript
var ProgressBar = require('progress');

var bar = new ProgressBar(':bar :current/:total', { total: 10 });
var timer = setInterval(function () {
  bar.tick();
  if (bar.complete) {
    clearInterval(timer);
  } else if (bar.curr === 5) {
      bar.interrupt('this message appears above the progress bar\ncurrent progress is ' + bar.curr + '/' + bar.total);
  }
}, 1000);
```

You can see more examples in the `examples` folder.

## License

MIT

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