# electron-progressbar: A small API for progress bars inside Electron windows and taskbars > electron-progressbar wraps Electron's BrowserWindow to show determinate or indeterminate progress bars, with CSS and taskbar support. It is simple, but its customHTML option is experimental and the API has limits. **AndersonMamede/electron-progressbar** — electron-progressbar provides an easy-to-use and highly customizable API to show and control progress bars on Electron applications. - Repository: https://github.com/AndersonMamede/electron-progressbar - Stars: 100 · Forks: 22 - Language: JavaScript - License: MIT - Published: 2026-08-17 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/andersonmamede-electron-progressbar ## What it solves and who it is for Electron apps often need to show progress for long tasks, such as file processing, downloads, or data imports. The built-in BrowserWindow.setProgressBar method only updates the taskbar icon, not the window content. electron-progressbar fills that gap by creating a separate BrowserWindow that displays a progress bar, and it optionally syncs that bar to the taskbar. The target user is an Electron developer who wants a ready-made progress window without building one from scratch. The README positions it as an easy-to-use and highly customizable API, and the examples show it being used from the main process after the app's ready event. It is not aimed at renderer-only UI, and it does not replace a full UI framework. It is a small utility for a specific need. ## How it works: a BrowserWindow wrapper with events The library works by creating an Electron BrowserWindow to host the progress bar. You instantiate a ProgressBar object with an options object, and it opens a window with the bar. The README says the progress bar is displayed within a BrowserWindow, and it also calls setProgressBar for taskbar display. The API exposes methods like setCompleted(), close(), isInProgress(), and isCompleted(), plus properties value, text, and detail. Events include ready, progress, completed, and aborted. The progress event fires with a value, which you can use to update the detail text. The indeterminate mode shows an animated bar when you cannot estimate the duration; determinate mode takes a value between 0 and 100. The data flow is straightforward: you create the bar, update its value or text, listen for completion, and close it. The library does not manage task logic; it only displays state you drive from your code. ## Getting it running: install and first example Installation is a single npm command: npm i electron-progressbar. The README shows a basic indeterminate example. You require the module, wait for the app's ready event, then create a new ProgressBar with options like text and detail. For a determinate bar, you set indeterminate: false and then update the value property as your task progresses. The constructor accepts an optional second parameter, electronApp, which you can pass if needed. The README notes that you must wait for the ready event because the progress bar is displayed in a BrowserWindow. The examples include a customHTML option for a custom HTML structure, but the README marks it experimental. The repository has an examples folder with more demos, including one for custom HTML. To use it, you would clone the repo and run those examples, but the README does not give the exact commands. ## Customization options: CSS, text, and window controls The main selling point is customization. You can change the appearance with CSS, set the text and detail strings, and even customize the BrowserWindow itself. The options table in the README lists properties like debug, which opens DevTools when set to true, and abortOnError, which likely aborts the bar on errors. The text and detail properties are mutable, so you can update them during a task. The value property is a number, presumably 0 to 100 for determinate mode. The customHTML option gives you full control over the HTML structure, but it is experimental, so you should expect instability. The README recommends using the standard options for most cases, which suggests that customHTML is for advanced users who need unique elements. The ability to style with CSS is a real advantage over a plain taskbar-only approach, because you can match the bar to your app's theme. ## Limitations and failure modes The most obvious limitation is that the library creates a separate window. That means your app will have a pop-up window for the progress bar, which may not fit a single-window design. You cannot embed the bar directly into an existing window's HTML; you get a new BrowserWindow. The customHTML feature is experimental, so it may break or change without notice. The README does not specify a minimum Electron version, which is a concern because Electron APIs evolve. The last push was in April 2024, but Electron releases frequently, and a library that relies on BrowserWindow internals may lag behind. Another failure mode is if you forget to wait for the ready event; the constructor will likely fail. Also, the aborted event fires when the user closes the window, but the README does not explain how to handle that gracefully. If your task is very short, the window may flash on screen, which could be annoying. The library is not designed for complex progress UIs with multiple bars or detailed status panels. ## Alternatives: build your own or use a UI framework The most direct alternative is to build a progress window yourself using Electron's BrowserWindow and HTML/CSS. That gives you full control over the layout and behavior, and you can avoid an extra dependency. You would use BrowserWindow.setProgressBar for the taskbar and a simple renderer with a progress element. The difference is that you write more code, but you are not tied to the library's API or its experimental features. Another alternative is to use a front-end framework like React or Vue with a progress component, but that adds a heavier stack. For a simple bar, a hand-rolled solution is often enough. The trade-off is time versus convenience. electron-progressbar saves you the boilerplate of creating a window, loading an HTML file, and handling IPC to update the bar. But if you need a custom design, you will end up writing that code anyway, so the library may not save you much. ## Maintenance and license The project is MIT licensed, which means you can use it in commercial applications with minimal restrictions, but you should read the license text for details. The repository has had recent releases, with v2.2.1 in April 2024, so it is not abandoned. However, the maintainer appears to be the sole author, and the README includes a donate button, which suggests it is a community project. The maintenance cost for you is low: it is a small dependency with a simple API. But you should monitor Electron updates because the library may not be updated immediately. The experimental customHTML feature is a risk; it could change in future releases. There is no documentation on upgrading between major versions, but the changelog is mentioned in the README. For a production app, you should pin the version and test after Electron upgrades. ## Conclusion Adopt electron-progressbar if you need a quick, dependency-light way to show a progress bar in a separate window and mirror it in the taskbar, and you are comfortable with Electron's main-process API. Skip it if you need complex custom layouts, if you are on newer Electron versions where the API may lag, or if you prefer a web-based UI that you fully control. Before adopting, verify that the version you install works with your Electron version and test the customHTML feature separately, since it is experimental. The project is MIT licensed and has had releases as recently as April 2024, but it is a small library with a narrow scope, so weigh whether you need more than a basic bar. ## FAQ ### What is the purpose of a progress bar in electron-progressbar? It gives an Electron application a progress bar that can be shown and controlled, both inside a BrowserWindow and in the taskbar, so progress information is visible without the user switching to the window. The indeterminate mode is for tasks whose duration cannot be calculated and the determinate mode is for tasks whose duration can. ### Do Electron apps need to be installed to use electron-progressbar? There is nothing separate to install beyond the app itself. The package is added to an existing Electron application with npm i electron-progressbar, and because the bar is displayed within an Electron BrowserWindow you must wait for Electron's ready event before constructing it, which means the host app and its window already exist. ### Can a progress bar reduce anxiety in an Electron app? The documentation makes no claim about user anxiety. What it does provide is the mechanism that would address it: text and detail strings you can rewrite while the task runs, and taskbar progress so the state stays visible when the window is in the background. ### Are electron-progressbar progress bars accurate? That depends on which mode you pick and on what your task reports. The determinate bar is intended for applications that can accurately calculate how long the task will take, the indeterminate bar is for those that cannot, and the value carried by the progress and aborted events comes from the caller rather than from the library. ## Sources - [Official README](https://github.com/AndersonMamede/electron-progressbar#readme) - [Project repository](https://github.com/AndersonMamede/electron-progressbar) - [Release notes](https://github.com/AndersonMamede/electron-progressbar/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/andersonmamede-electron-progressbar