frogress-bar v0.1.0

frogress-bar

React based progress bar for command-line/terminal applications

Features

• 🌱 Simple & Easy to use
• 🔥 Supports single & multiple progress bar
• 🎨 Supports 256 & Truecolor
• 💧 Responsive size
• ⭐️ Fully customizable

Installation

# npm
npm install frogress-bar

# yarn
yarn add frogress-bar

Usage

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();

Demo

Demo

Demo

Documentation

create

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 |

/* 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<string, string>;
}

function create(config?: ProgressConfig): ProgressBar;

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 {}.

remove

Unmount & Remove specified ProgressBar from current context.

• Parameters | Name | Type | Required | |:--|:--|:--| | progressBar | ProgressBar | Yes |
• Return Value | Type | |:--| | void |

/* interfaces */

function remove(progressBar: ProgressBar): void;

removeAll

Unmount & Remove all progress bars from current context.

• Return Value | Type | |:--| | void |

/* interfaces */

function removeAll(): void;

count

Returns the current instance count of the progress bar.

• Return Value | Type | |:--| | number |

/* interfaces */

function count(): number;

setOptions

Applies the options to the Frogress container.

• Parameters | Name | Type | Required | |:--|:--|:--| | options | ContainerOptions | Yes |
• Return Value | Type | |:--| | void |

/* interfaces */

interface ContainerOptions {
  refreshRate: number;
}

function setOptions(options: ContainerOptions): void;

• refreshRate: Defaults to 50.

ProgressBar.start

Render progress bar.

• Parameters | Name | Type | Required | |:--|:--|:--| | options | ProgressValues | Yes |
• Return Value | Type | |:--| | void |

/* interfaces */

interface ProgressValues {
  value: number;
  total?: number;
  placeholder?: Record<string, string>;
}

function start(values: ProgressValues): void;

• value: current progress value.
• total: total progress value.
• placeholder: Key-Value data that replace of template's placeholders.

ProgressBar.update

Set new states and re-render progress bar.

• Parameters | Name | Type | Required | |:--|:--|:--| | options | ProgressValues | Yes |
• Return Value | Type | |:--| | void |

/* interfaces */

interface ProgressValues {
  value: number;
  total?: number;
  placeholder?: Record<string, string>;
}

function update(values: ProgressValues): void;

• value: current progress value.
• total: total progress value.
• placeholder: Key-Value data that replace of template's placeholders.

ProgressBar.stop

Unmount progress bar.

!NOTE
If you want to exit the process, you should remove all of progress bars using remove() or removeAll()

function stop(): void;

Template

!WARNING If you use reserved placeholder name, it will be overwritten to internal value of Frogress.

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% value

Development

# Lint
yarn lint

# Build
yarn build

# Run demo code
yarn start demo/{name}.ts

Resources

• Logo image generated by DALL-E

License

MIT