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…
- Collect orders
- Match payments
- Check totals
- 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/uinpm install @brand-studio/uiyarn add @brand-studio/uibun add @brand-studio/uiInstall the peer dependencies
npm install react react-domImport the stylesheet once
import '@brand-studio/ui/styles.css';Wrap your app in a brand theme
import { BrandTheme, ProgressBar } from '@brand-studio/ui'; import brand from './brand.json'; <BrandTheme palette={brand.tokens} mode="system"> {/* your app */} </BrandTheme>
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
progressbarnamed bylabel, with its value in percent. Near the end, screen readers hear the finishing words instead of 99. statusis 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
| Prop | Type | Default |
|---|---|---|
value | number | – |
label | React.ReactNode | – |
status? | React.ReactNode | – |
steps? | string[] | – |
step? | number | 0 |
onCancel? | (() => void) | – |
action? | React.ReactNode | – |
cancelLabel? | string | 'Cancel' |
finishingLabel? | string | 'Finishing up' |
doneLabel? | string | 'Done' |
className? | string | '' |