A small browser utility

Show that work
has started.

ProgressBeam adds a thin progress indicator to the top of a page. It is built for navigation, Ajax requests, and any other operation where the result takes a moment.

npm install progressbeam v MIT licensed

Try it

The bar is real. It appears at the top of the page when an operation starts and leaves when it finishes.

Live demo Ready

Current state

Waiting for an action

Use it

No framework runtime is required. Import the module and the stylesheet, then connect the calls to your own request lifecycle.

Installshell

npm install progressbeam

Basic lifecycleapp.js

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

ProgressBeam.start()
// load a route or request
ProgressBeam.done()

The API

Small surface area, explicit states. Use fail() when the work did not finish normally.

CallWhat it does

start()Starts the indicator and trickles forward.

set(0.4)Sets a known progress value from 0 to 1.

inc()Moves forward without reaching completion.

done()Completes and removes the indicator.

fail()Marks the current operation as failed.

dec()Moves backward; does nothing while idle.

promise(p)Tracks a promise until it settles.

cancel()Removes the indicator and resets its state.

reset()Removes the indicator and restores default settings.

pause() / resume()Pauses or resumes automatic trickling.

configure(options)Updates the indicator settings.

on(event, fn) / off()Subscribes or unsubscribes lifecycle handlers.

Tune it

Colors, timing, placement, and labels are settings. Change them once at startup.

Settingsapp.js

ProgressBeam.configure({
  barColor: '#2563eb',
  failureColor: '#dc2626',
  height: '3px',
  position: 'bottom',
  delay: 120
})

Wire it up

Small helpers connect the bar to fetch, routers, and frameworks. Each ships dependency-free.

Fetch trackingapp.js

import { createFetchTracker } from 'progressbeam/adapters/history'
const trackedFetch = createFetchTracker(ProgressBeam)
await trackedFetch('/api/data')

Reactapp.jsx

import { useProgressBeam } from 'progressbeam/adapters/react'
useProgressBeam(isLoading)

Progress feedback for the part of the interface that has not arrived yet.