React based progress bar for command-line/terminal applications

React based progress bar for command-line/terminal applications
- 🌱 Simple & Easy to use
- 🔥 Supports single & multiple progress bar
- 🎨 Supports 256 & Truecolor
- 💧 Responsive size
- ⭐️ Fully customizable
``bashnpm
npm install frogress-bar
Usage
`ts
import * as Frogress from 'frogress-bar';// 1. Create new progress bar
const progressBar = Frogress.create({
total: 100,
template: '{label} {progress} ({percentage})',
placeholder: {
label: 'Downloader',
},
});
// 2. Render progress bar
progressBar.start({ value: 0 });
await download({
onProgress: (percent) => {
// 3. Update progress bar state
progressBar.update({ value: percent });
},
});
// 4. Unmount progress bar#
progressBar.stop();
// 5. Remove progress bar
Frogress.remove(progressBar);
Frogress.removeAll();
`
Multiple progress bars
Custom colored progress bars
Re-use progress bar
Documentation
$3
Create a new
ProgressBar instance.
It can be called multiple times for multiple progress bars.- Parameters
| Name | Type | Required |
|:--|:--|:--|
| options |
ProgressConfig | No |
- Return Value
| Type |
|:--|
| ProgressBar |`ts
/ interfaces /interface ProgressConfig {
/**
* Defaults to
0.
*/
value?: number;
/**
* Defaults to 100.
*/
total?: number;
/**
* Defaults to 50 (Depend on terminal size).
*/
progressBarSize?: number;
/**
* Defaults to '█'.
*/
activeChar?: string;
/**
* Defaults to '░'.
*/
inactiveChar?: string;
/**
* Template string.
*
* Defaults to '{progress}'.
*/
template?: string;
/**
* Key-Value data that replace of template's placeholders.
*
* Defaults to {}.
*/
placeholder?: Record;
}function create(config?: ProgressConfig): ProgressBar;
``ts
import * as Frogress from 'frogress-bar';const progressBar = Frogress.create(config);
`-
value: Defaults to 0.
- total: Defaults to 100.
- progressBarSize: Defaults to 50 (Depend on terminal size).
- activeChar: Defaults to '█'.
- inactiveChar: Defaults to '░'.
- template: Template string. Defaults to '{progress}'.
- placeholder: Key-Value data that replace of template's placeholders. Defaults to {}.$3
Unmount & Remove specified
ProgressBar from current context.- Parameters
| Name | Type | Required |
|:--|:--|:--|
| progressBar |
ProgressBar | Yes |
- Return Value
| Type |
|:--|
| void |`ts
/ interfaces /function remove(progressBar: ProgressBar): void;
`$3
Unmount & Remove all progress bars from current context.
- Return Value
| Type |
|:--|
|
void |`ts
/ interfaces /function removeAll(): void;
`$3
Returns the current instance count of the progress bar.
- Return Value
| Type |
|:--|
|
number |`ts
/ interfaces /function count(): number;
`$3
Applies the options to the Frogress container.
- Parameters
| Name | Type | Required |
|:--|:--|:--|
| options |
ContainerOptions | Yes |
- Return Value
| Type |
|:--|
| void |`ts
/ interfaces /interface ContainerOptions {
refreshRate: number;
}
function setOptions(options: ContainerOptions): void;
`-
refreshRate: Defaults to 50.$3
Render progress bar.
- Parameters
| Name | Type | Required |
|:--|:--|:--|
| options |
ProgressValues | Yes |
- Return Value
| Type |
|:--|
| void |`ts
/ interfaces /interface ProgressValues {
value: number;
total?: number;
placeholder?: Record;
}
function start(values: ProgressValues): void;
`-
value: current progress value.
- total: total progress value.
- placeholder: Key-Value data that replace of template's placeholders.$3
Set new states and re-render progress bar.
- Parameters
| Name | Type | Required |
|:--|:--|:--|
| options |
ProgressValues | Yes |
- Return Value
| Type |
|:--|
| void |`ts
/ interfaces /interface ProgressValues {
value: number;
total?: number;
placeholder?: Record;
}
function update(values: ProgressValues): void;
`-
value: current progress value.
- total: total progress value.
- placeholder: Key-Value data that replace of template's placeholders.$3
Unmount progress bar.
> [!NOTE]
> If you want to exit the process, you should remove all of progress bars using remove() or removeAll()
`ts
function stop(): void;
`Template
> [!WARNING]
> If you use reserved placeholder name, it will be overwritten to internal value of Frogress.
`ts
const templateString = 'Template {label} {progress} | {test}';progressBar.update({
placeholder: {
// Plain placeholder
label: '#1',
// Placeholder with color
test: Frogress.color('Colored!!', '#00ffff'),
},
});
// Preview
// Template #1 ██████████████░░░░░░░░░░░░░░░░ | Colored!!
`- Reserved placeholders
-
{progress}: Progress bar (required)
- {value}: Current value
- {total}: Total value
- {percentage}: current / total * 100% valueDevelopment
`bash
Lint
yarn lintBuild
yarn buildRun demo code
yarn start demo/{name}.ts
``- Logo image generated by DALL-E