# Progress Bar

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

```tsx
'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

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, ProgressBar } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { ProgressBar } from '@brand-studio/ui';
```

```tsx
<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

| 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` | `''` |

Source: https://brandstudio.js.org/docs/components/progress-bar/
