# ProgressBar

**When to use:** Visual progress indicator — file uploads, multi-step completion, storage usage, stacked stats (e.g. budget breakdown).

**Keywords:** progress meter, loading bar

**Import:** `import { ProgressBar } from '@ahrowe/ui'`

```tsx
import { ProgressBar, ThemeColor } from '@ahrowe/ui';

// Simple percentage
<ProgressBar progress={75} total={100} />

// Single progress with label, in a theme colour
<ProgressBar
  total={100}
  progress={{ amount: 60, label: 'Used', color: ThemeColor.Warn }}
/>

// Stacked / segmented bar
<ProgressBar
  total={100}
  progress={[
    { amount: 40, label: 'Category A', color: '#6200ea' },
    { amount: 30, label: 'Category B', color: '#03dac6' },
    { amount: 20, label: 'Category C', color: '#018786' },
  ]}
/>
```

**Size:** the bar fills its container's width, at least 100px wide and 10px tall. A segment's
`label` is drawn inside that segment, which makes the bar as tall as the text.

**Screen readers:** the bar is a `progressbar` from 0 to `total`, its value the sum of every
segment. Name it with `aria-label` (`aria-label='Upload'`). A stacked breakdown that is not progress
toward anything, such as a budget split, can take `role='img'` with an `aria-label` that says it.

**Key props:**

| Prop | Type | Description |
|------|------|-------------|
| `total` | `number` | Maximum value (100% baseline) |
| `progress` | `number \| Progress \| Progress[]` | Current value(s) |

**Progress object:**

```ts
{ amount: number; label?: string; color?: ColorValue; class?: string }
```

`color` is a `ThemeColor` or any CSS colour (see [ThemeColor.md](ThemeColor.md)), `--primary-color`
when unset. A label on a coloured segment is black or white, whichever reads on it.

**Theming:** override theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`; falls back to a built-in default when unset:

| Variable | Falls back to |
|----------|---------------|
| `--progress-bar-track-color` | `color-mix(in srgb, currentcolor 20%, transparent)`: a tint of the text colour, visible on a Card as on the page |

```tsx
// Theme-wide, via ThemeProvider
const theme: Theme = {
  id: 'brand',
  variables: { '--progress-bar-track-color': '#2a2a2a' },
};

// Or one-off via style
<ProgressBar progress={60} style={{ '--progress-bar-track-color': '#2a2a2a' } as React.CSSProperties} />
```

**Slots:** `root` `fill` `label`