# Progress

## Overview

The progress component styles the native `<progress>` element for determinate and indeterminate task progress.

Use it when the interface needs to show completion amount without naming every step, or when a stepper would be too long to scan comfortably. Use the stepper component instead when the user needs to understand a short sequence of named steps and their current position within that sequence.

## When to use

Use progress to show overall task completion without naming every step, including when a sequence is too long for a stepper.

## When not to use

Do not use progress when users need to understand a short sequence of named steps and their current position; use a stepper.

## Usage

For known progress, provide `value` and `max`:

```html
<progress value="70" max="100">70%</progress>
```

For unknown or ongoing progress, omit `value`:

```html
<progress></progress>
```

Keep fallback text inside the element so older assistive technology and browsers without full progress support still have a readable value.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- PRG-001: The filled bar uses the primary color through `--progress-value-color`.
- PRG-002: The track uses the subtle primary color through `--progress-track-color`.
- PRG-003: Determinate progress uses the browser's native `value` and `max` behavior.
- PRG-004: Indeterminate progress animates a solid bar across the track when `value` is omitted.
- PRG-005: The indeterminate animation respects `prefers-reduced-motion: reduce` by stopping the animation and centering the bar.
- PRG-006: The component uses native progress pseudo-elements for Chromium, Safari, and Firefox.
## Accessibility

- Use `value` and `max` only when the amount of progress is known.
- Omit `value` for indeterminate work instead of setting a placeholder value.
- Include concise fallback text for determinate progress, such as `70%`.
- If the value is not intederminate, use `aria-valuenow` for assistive technologies.
- Add a visible label, `aria-label`, or `aria-labelledby` when surrounding text does not clearly identify what the progress bar represents.
- Do not use color alone as the only progress explanation when a precise value matters; include text nearby when users need the number.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--progress-border-radius` | `<length>` | Sets the rounding for progress tracks and clipping; change it to make progress bars pill-shaped or squared. |
| `--progress-height` | `<length>` | Sets the block size of progress bars; change it when progress indicators need more visual weight or denser layout. |
| `--progress-track-color` | `<color>` | Sets the unfilled track color for native and custom progress states; change it when the remaining portion needs different contrast. |
| `--progress-value-color` | `<color>` | Sets the filled progress color and native accent color; change it when completion should use a different brand or status color. |

## Depends On

- `--color-accent`
- `--color-primary`
- `--color-primary-subtle`
- `--layout-control-radius`