progressbeam

ProgressBeam

ProgressBeam is a slim, dependency-free progress indicator for browser applications. Use it while a page loads, a route changes, or an asynchronous operation is in flight.

• Zero runtime dependencies; ESM, CommonJS, and direct-browser builds
• TypeScript declarations with type-tested public API
• Valid progressbar semantics, labeled status, reduced-motion support
• Lifecycle events plus explicit fail, cancel, pause, and reset
• Framework adapters for fetch, routers, React, Next.js, Vue, TanStack
• Verified in real Chromium/Firefox/WebKit with enforced size budgets

See it in motion

Captured from the published runtime moving through progress, pause, failure, reset, and completion. GitHub selects the dark variant when the reader uses dark mode.

Install

npm install progressbeam

With a module bundler:

import ProgressBeam from 'progressbeam';
import 'progressbeam/progressbeam.css';

For direct browser use, load the published files:

<link rel="stylesheet" href="progressbeam.css">
<script src="progressbeam.js"></script>

Safe to import during SSR; see Content Security Policy and SSR.

Usage

Start and finish around an asynchronous operation:

ProgressBeam.start();

fetch('/api/data')
  .finally(() => ProgressBeam.done());

Set a known percentage or increment the current value:

ProgressBeam.set(0.4);
ProgressBeam.inc();
ProgressBeam.done();

Track a promise, thenable, or jQuery Deferred:

ProgressBeam.promise(fetch('/api/data'));

Use cancel() for an aborted operation and fail() when the indicator should remain visible as a failure:

ProgressBeam.start().fail();
ProgressBeam.cancel();

API

render(), remove(), reset(), isStarted(), isRendered(), and status are also available for integrations that need direct state or DOM control.

Lifecycle

stateDiagram-v2
    [*] --> idle
    idle --> running: start / set
    idle --> paused: pause
    running --> paused: pause
    paused --> running: resume
    running --> completing: done / set(1)
    completing --> idle: fade ends
    completing --> idle: cancel / reset
    running --> failed: fail
    failed --> idle: done / cancel / reset
    running --> idle: cancel / reset
    paused --> idle: cancel / reset
    failed --> failed: fail

start() and set() move out of idle; done() runs the completion fade; fail() holds the visible failure state; cancel() and reset() return to idle immediately, with reset() also restoring default settings.

Configuration

ProgressBeam.configure({
  barColor: '#2563eb',
  spinnerColor: '#0f172a',
  failureColor: '#dc2626',
  height: '3px',
  zIndex: 2000,
  delay: 120,
  parent: '#app'
});

Navigation events

Connect ProgressBeam to a navigation library with standard DOM listeners:

document.addEventListener('turbolinks:click', () => ProgressBeam.start());
document.addEventListener('turbolinks:render', () => ProgressBeam.done());

document.addEventListener('pjax:start', () => ProgressBeam.start());
document.addEventListener('pjax:end', () => ProgressBeam.done());

Framework adapters

Zero-dependency helpers ship under progressbeam/adapters/* (ESM only). Framework peers are required only by the adapter that uses them:

// Vanilla: track fetch() calls (no peers)
import { createFetchTracker } from 'progressbeam/adapters/history';
const trackedFetch = createFetchTracker(ProgressBeam);
await trackedFetch('/api/data');

// Vanilla: router guards (vue-router compatible)
import { bindRouterGuards } from 'progressbeam/adapters/history';
const unbind = bindRouterGuards(router, ProgressBeam);

// React (peer: react)
import { useProgressBeam } from 'progressbeam/adapters/react';
useProgressBeam(isLoading);

// Next.js App Router (peer: react)
import { createAppRouterTracker } from 'progressbeam/adapters/next';
const tracker = createAppRouterTracker(ProgressBeam);
tracker.finish(usePathname()); // inside an effect keyed on the pathname

// Vue (peer: vue)
import { useProgressBeam } from 'progressbeam/adapters/vue';
useProgressBeam();

// TanStack Router (no runtime dependency)
import { bindTanStackRouter } from 'progressbeam/adapters/tanstack';
const unbind = bindTanStackRouter(router, ProgressBeam);

Accessibility and customization

The default template uses role="progressbar", aria-valuemin, aria-valuemax, and aria-valuenow. The spinner is hidden from assistive technology, and reduced-motion preferences disable its animation.

Custom templates must include an element matching barSelector. Templates are inserted as HTML; never pass untrusted input to template.

Content Security Policy and SSR

The package is safe to import during SSR: without a document only the status model advances, and render() returns null. Call DOM methods after a browser document is available.

CSP notes:

• script-src: the distributed files are static scripts with no eval or new Function (enforced by the source-hygiene suite), so they can be allow-listed or hashed like any first-party script.
• style-src: bar positioning is applied through element styles at runtime, so a strict style-src policy needs 'unsafe-inline' for the indicator to animate. The stylesheet itself is a static file.
• template is assigned via innerHTML; treat it as trusted markup only.
• No <style> elements are injected at runtime, so no nonce plumbing is needed.

Support and development

The maintained browser target is current Chromium, Firefox, and WebKit. Node.js 18 or newer is the package runtime floor for imports and SSR. Use a currently supported Node.js release in production.

See MIGRATION.md for changes from ProgressBeam 0.2.0 and CONTRIBUTING.md for development and verification commands.

Acknowledgments

ProgressBeam continues NProgress by Rico Sta. Cruz, built with help from its contributors. The original MIT license and copyright notice are preserved in License.md.

Citation

If you use ProgressBeam in your work, please cite it. The easiest way is the Cite this repository button in the GitHub sidebar, which exports APA and BibTeX from CITATION.cff. A ready-made BibTeX entry for this release:

@misc{Attri2026ProgressBeam,
  author = {Attri, Krishi},
  title = {ProgressBeam},
  year = {2026},
  version = {1.1.0},
  doi = {10.5281/zenodo.22821136},
  url = {https://github.com/Archerkattri/progressbeam}
}

License

ProgressBeam is released under the MIT License.