electron-progressbar

electron-progressbar provides an easy-to-use and highly customizable API to show and control progress bars on Electron applications.

You can customize the aspects of the windows (electron's BrowserWindow), progress bars' visual aspects (CSS), texts and also all visible information.

Demo

Indeterminate progress bar:

Determinate progress bar:


Additionally, a progress bar is also displayed in the taskbar (through BrowserWindow's setProgressBar). This enables a window to provide progress information to the user without the user having to switch to the window itself.

taskbar for indeterminate progress bar:

taskbar for determinate progress bar:

Table of Contents

• Installation
• Examples
  • Indeterminate progress bar
  • Determinate progress bar
  • More examples
• API
  • Methods
    • .new ProgressBar(options, [electronApp])
    • .getOptions() ⇒ object
    • .on(eventName, listener) ⇒ reference to this
      • Events
        • ready
        • progress
        • completed
        • aborted
    • .setCompleted()
    • .close()
    • .isInProgress() ⇒ boolean
    • .isCompleted() ⇒ boolean
  • Properties
    • value ⇒ number
    • text ⇒ string
    • detail ⇒ string
• Changelog
• License

Installation

Install with npm:

$ npm i electron-progressbar

Examples

Indeterminate progress bar

Example of an indeterminate progress bar - used when your application can't calculate how long the task will last:

const {app} = require('electron');
const ProgressBar = require('electron-progressbar');

app.on('ready', function() {
  var progressBar = new ProgressBar({
    text: 'Preparing data...',
    detail: 'Wait...'
  });
  
  progressBar
    .on('completed', function() {
      console.info(`completed...`);
      progressBar.detail = 'Task completed. Exiting...';
    })
    .on('aborted', function() {
      console.info(`aborted...`);
    });
  
  // launch a task...
  // launchTask();
  
  // when task is completed, set the progress bar to completed
  // ps: setTimeout is used here just to simulate an interval between
  // the start and the end of a task
  setTimeout(function() {
    progressBar.setCompleted();
  }, 3000);
});

Determinate progress bar

Example of a determinate progress bar - used when your application can accurately calculate how long the task will last:

const {app} = require('electron');
const ProgressBar = require('electron-progressbar');

app.on('ready', function() {
  var progressBar = new ProgressBar({
    indeterminate: false,
    text: 'Preparing data...',
    detail: 'Wait...'
  });
  
  progressBar
    .on('completed', function() {
      console.info(`completed...`);
      progressBar.detail = 'Task completed. Exiting...';
    })
    .on('aborted', function(value) {
      console.info(`aborted... ${value}`);
    })
    .on('progress', function(value) {
      progressBar.detail = `Value ${value} out of ${progressBar.getOptions().maxValue}...`;
    });
  
  // launch a task and increase the value of the progress bar for each step completed of a big task;
  // the progress bar is set to completed when it reaches its maxValue (default maxValue: 100);
  // ps: setInterval is used here just to simulate the progress of a task
  setInterval(function() {
    if(!progressBar.isCompleted()){
      progressBar.value += 1;
    }
  }, 20);
});

More examples are available in folder examples.

API

Methods

new ProgressBar(options, [electronApp])

Create a new progress bar. Because electron's BrowserWindow is used to display the progress bar and it only works after electron's "ready" event, you have wait for the "ready" event before creating a progress bar; optionally, you can just pass electron's app as a second parameter (electronApp).

getOptions() ⇒ object

Return a copy of all current options.

on(eventName, listener) ⇒ reference to this

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added and called multiple times.

Returns a reference to this so that calls can be chained.

Events

setCompleted()

Set progress bar as complete. This means the whole task is finished.

If progress bar is indeterminate, a manual call to this method is required because it's the only way to complete the task and trigger the complete event, otherwise the progress bar would be displayed forever.

close()

Close progress bar window. If progress bar is not completed yet, it'll be aborted and event aborted will be fired.

isInProgress() ⇒ boolean

Return true if progress bar is currently in progress, i.e., it hasn't been completed nor aborted yet, otherwise false.

isCompleted() ⇒ boolean

Return true if progress bar is completed, otherwise false.

Properties

value ⇒ number

Get or set progress bar's value. Only available for determinate progress bar.

text ⇒ string

Get or set the text. This information is shown inside the window and above the progress bar.

detail ⇒ string

Get or set the detail. This information is shown between text and the progress bar element. Useful to display any detailed information, e.g., the current status in real time or the current step of the task.

Changelog

Changelog

License

MIT. See LICENSE.md for details.