Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bubkoo/ascii-progress
🍓 Ascii progress-bar(s) in the terminal.
https://github.com/bubkoo/ascii-progress
ascii nodejs progress progress-bar
Last synced: 7 days ago
JSON representation
🍓 Ascii progress-bar(s) in the terminal.
- Host: GitHub
- URL: https://github.com/bubkoo/ascii-progress
- Owner: bubkoo
- License: mit
- Created: 2016-03-02T17:12:11.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-01-01T03:22:46.000Z (26 days ago)
- Last Synced: 2025-01-13T03:06:41.706Z (14 days ago)
- Topics: ascii, nodejs, progress, progress-bar
- Language: TypeScript
- Homepage:
- Size: 6.68 MB
- Stars: 206
- Watchers: 4
- Forks: 21
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
- awesome-ascii - ascii-progress
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)