Progress Bar

A bar for a job of known length that never moves backwards, with optional steps and Cancel.

Building the March sales report

Reading 412 orders from the shop…

Step 1 of 40%

  1. Collect orders
  2. Match payments
  3. Check totals
  4. Write the report
'use client';

import { useEffect, useState } from 'react';
import { Button, ProgressBar } from '@brand-studio/ui';

const steps = ['Collect orders', 'Match payments', 'Check totals', 'Write the report'];
const doing = ['Reading 412 orders from the shop', 'Matching 398 payments to their orders', 'Comparing each total with the ledger', 'Laying out 6 pages and charts'];

export default function ProgressBarDemo() {
  const [value, setValue] = useState(0);
  const [stopped, setStopped] = useState(false);
  const done = value >= 100;
  useEffect(() => {
    if (stopped || done) return;
    const timer = window.setTimeout(() => setValue(current => Math.min(100, current + 2.5)), 250);
    return () => clearTimeout(timer);
  }, [value, stopped, done]);
  const step = Math.min(steps.length - 1, Math.floor(value / 25));
  const restart = () => { setValue(0); setStopped(false); };
  return (
    <div style={{ width: '100%', maxWidth: 440 }}>
      <ProgressBar
        value={value}
        label="Building the March sales report"
        status={stopped ? 'Stopped. Nothing was changed.' : done ? 'Your report is ready.' : `${doing[step]}…`}
        steps={steps}
        step={step}
        onCancel={stopped ? undefined : () => setStopped(true)}
        action={(done || stopped) && <Button onClick={restart}>{done ? 'Run again' : 'Start again'}</Button>}
      />
    </div>
  );
}

Installation

pnpm add @brand-studio/ui

Usage

import { ProgressBar } from '@brand-studio/ui';
<ProgressBar
  value={percent}
  label="Building the March sales report"
  status="Matching 398 payments to their orders…"
  steps={['Collect orders', 'Match payments', 'Check totals', 'Write the report']}
  step={1}
  onCancel={cancelJob}
/>

Use it for a wait of more than about ten seconds whose length you can measure. The bar holds its highest value, so a lower value never moves it backwards; pass 0 to start a new job. At 99% it says finishingLabel instead of a number, and at 100% it says doneLabel. Put the next step, such as opening the result, in action.

Accessibility

  • The bar is a progressbar named by label, with its value in percent. Near the end, screen readers hear the finishing words instead of 99.
  • status is a polite live region, so each new step is announced once without moving focus.
  • Finished steps carry "(done)" for screen readers; the tick marks are hidden from them.

API Reference

PropTypeDefault
valuenumber–
labelReact.ReactNode–
status?React.ReactNode–
steps?string[]–
step?number0
onCancel?(() => void)–
action?React.ReactNode–
cancelLabel?string'Cancel'
finishingLabel?string'Finishing up'
doneLabel?string'Done'
className?string''

Still, Deskhand and Hollis are fictional brands. The coffee photographs are original generated artwork. @brand-studio/ui is MIT licensed.