# ascii-progress
> Ascii progress-bar(s) in the terminal.
Latest version **2.0.0** (published 2022-10-08) · MIT license · 0 weekly downloads
## Install
```sh
npm install ascii-progress
pnpm add ascii-progress
yarn add ascii-progress
bun add ascii-progress
```
## Health
**Score 30/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.0.0 |
| Published | 2022-10-08 |
| First published | 2016-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 1.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 217 |
| Author | bubkoo |
| Maintainers | bubkoo |
| Keywords | progress, bar, meter, ascii, status, console, terminal, ansi.js |
## Links
- npm: https://www.npmjs.com/package/ascii-progress
- Repository: https://github.com/bubkoo/ascii-progress
- Issues: https://github.com/bubkoo/ascii-progress/issues
- npm.io page: https://npm.io/package/ascii-progress
## Dependencies (3)
- [ansi.js](https://npm.io/package/ansi.js.md) ^1.0.0
- [on-new-line](https://npm.io/package/on-new-line.md) ^1.0.0
- [get-cursor-position](https://npm.io/package/get-cursor-position.md) ^2.0.0
## Alternatives
- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads
## Recent versions
- 2.0.0 (latest) — 2022-10-08
- 1.0.5 — 2016-11-01
- 1.0.4 — 2016-10-19
- 1.0.3 — 2016-09-14
- 1.0.2 — 2016-06-03
- 1.0.1 — 2016-04-20
- 1.0.0 — 2016-04-19
## README
ascii-progress
Ascii progress-bar(s) in the terminal.
**Features**:
- Support multi progress-bars.
- Relative and absolute width.
- Colorful bar and text.
- Highly customizable.
## Install
```
$ npm install ascii-progress
```
## Usage
> For more usage see the [examples](https://github.com/bubkoo/ascii-progress/blob/master/examples)
```javascript
const { ProgressBar } = require('ascii-progress');
const bar = new ProgressBar({
schema: ':bar',
total : 10,
});
const iv = setInterval(function () {
bar.tick();
if (bar.completed) {
clearInterval(iv);
}
}, 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.
- `schema` - template string of the progress bar. Default `" [:bar] :current/:total :percent :elapseds :etas'"`.
- `total` - total number of ticks to complete. Default `100`.
- `current`- number of completed ticks. Default `0`.
- `width` - display width, percentage or less than `1` is relative the terminal's width. Default `60`.
- `fixedWidth` - do not adjust the bar based on the terminal size
- `filled`- completion character. Default `"▇"`.
- `blank` - blank character. Default `"-"`.
- `clean` - clear the progress bar on completion. Default `false`.
- `callback` - optional function to call when the progress bar completes.
### Properties
- `schema`
- `total`
- `current`
- `completed`
### Methods
- `setSchema(schema, refresh/tokens)` - Update the schema of the progress bar. If `refresh` or `tokens` is truely the progress bar will be refreshed.
- `tick(delta, tokens)` - Update ticks of the progress bar by `delta`, then render the progress bar with optional `tokens`.
- `update(ratio, tokens)` - Update the progress bar to `ratio` by percentage, then render the progress bar with optional `tokens`.
- `clear()` - Clean the progress bar in the terminal.
## Schema
The schema defines appearance the progress bar. Few inner tokens and many formatting methods can be used to customer you progress bar.
### Tokens
These are tokens you can use in the format of your progress bar.
- `:filled` Completed part of the progress bar.
- `:blank` Blank part of the progress bar.
- `:bar` Whole progress bar, equal to `:completed:blank`.
- `:current` Current tick number.
- `:total` Total ticks.
- `:percent` Completion percentage.
- `:elapsed` Time elapsed in seconds.
- `:eta` Estimated completion time in seconds.
### Custom Tokens
You can define custom tokens by adding a `{name: value}` object parameter to your method (`tick()`, `update()`, etc.) calls.
```javascript
const bar = new ProgressBar({
schema: ':current: :token1 :token2',
total : 3,
});
bar.tick({
'token1': "Hello",
'token2': "World!"
})
bar.tick(2, {
'token1': "Goodbye",
'token2': "World!"
})
```
The above example would result in the output below.
```
1: Hello World!
3: Goodbye World!
```
### Colors
Color names can be use in schema:
```
:bar.red :percent.green
```
Then the progress bar will be red, and the percentage will be green.
All available color names:
- red
- cyan
- blue
- grey
- white
- black
- green
- yellow
- magenta
- brightRed
- brightBlue
- brightCyan
- brightWhite
- brightBlack
- brightGreen
- brightYellow
- brightMagenta
And with the `bg` prefix, such as `bgRed`, the color will be applied to the background.
```
:bar.red.bgBlue
```
The above progress bar has blue background and red foreground.
### Gradient
```
:bar.gradient(red,blue)
```
The arguments can be color names or hex color:
- red
- cyan
- blue
- grey
- white
- black
- green
- yellow
- magenta
- \#xxxxxx
### Font style
Same as color names, font style can also be assigned by name:
- bold
- italic
- inverse
- underline
```
:bar.red :percent.green.bold
```
The percentage is green and bold.
## Contributing
Please let us know how can we help. Do check out [issues](https://github.com/bubkoo/ascii-progress/issues) for bug reports or suggestions first.
To become a contributor, please follow our [contributing guide](/CONTRIBUTING.md).
## License
The scripts and documentation in this project are released under the [MIT License](LICENSE)
---
_Source: https://npm.io/package/ascii-progress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._