# Progress

A bar showing how far a task has run, or that it is running.

```ehtml Example
import { Progress } from "@elements/ui/progress";

<Progress value={33} />
<Progress value={state.uploaded} label="Upload progress" showValue />
<Progress value={null} label="Preparing" />
<Progress value={3} max={10} showValue getValueLabel={(v, max) => `${v} of ${max} files`} />
```

## Parts

| Part | What it is |
|---|---|
| `.progress-label` | The label, from label. |
| `.progress-value` | The value text, from showValue. |
| `.progress-track` | role=progressbar, the bar. |
| `.progress-indicator` | The fill, moved with transform. --progress-color recolors it. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `number \| null` | `null` | Progress so far, clamped to min and max. null is indeterminate. |
| `min` | `number` | `0` | Start of the range. |
| `max` | `number` | `100` | End of the range; the value at max is complete. |
| `label` | `string` | `""` | Visible label that names the bar. |
| `showValue` | `boolean` | `false` | Shows the value text beside the label. |
| `format` | `Intl.NumberFormatOptions \| null` | `null` | Formats the value itself. Default: the percent of the range. |
| `locale` | `string` | `""` | Locale for the value text. |
| `getValueLabel` | `((value: number, max: number) => string) \| null` | `null` | Text for the value and aria-valuetext, such as "3 of 10 files". |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Track height. |
| `class` | `string` | `""` | Extra classes on the root. Set --progress-color to recolor. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the progressbar: aria-label when there is no visible label, id, data-\*. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-state` | `"indeterminate" \| "loading" \| "complete"` | root, track, indicator |
| `data-value` | the clamped value; absent while indeterminate | root, indicator |
| `data-max` | max | root, indicator |
| `data-complete, data-indeterminate, data-progressing` | present for the matching state | every part |

## Accessibility

- role="progressbar" with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext; aria-valuenow is left out while indeterminate.
- The label names the bar through aria-labelledby. Without one, pass aria-label through attrs.
- The visible value is aria-hidden because aria-valuetext says the same thing.
- Under prefers-reduced-motion the indeterminate slide becomes a slow pulse and value changes do not animate.

## See also

- [Badge](badge): A small label for a status, a count or a category, built on the pill.
- [Card](card): A surface with a header, body and footer, built on the base card styles.
- [Alert](alert): A callout that draws attention to a message, with an icon, a title and an action.
- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [Kbd](kbd): A keyboard key or shortcut, as text.
- [Separator](separator): A horizontal or vertical rule between content, semantic or decorative.