The Progress Bar component is a linear pill-style indicator that visually represents the completion percentage of a determinate task or ongoing activity in indeterminate mode.
- Use determinate mode when completion percentage is known (e.g., file uploads, form submission, data saving).
- Use indeterminate mode when duration is unknown but activity should be shown.
- Provide feedback for operations expected to take longer than 2 seconds.
- Pill-style bar (large): rounded ends, colored fill, dotted unfilled track.
- Pill-style bar (small): rounded ends, colored fill, solid unfilled track.
- Labels above bar: main label left, percentage label right.
- For instant operations (less than 1 second); adds unnecessary visual noise.
- As an interactive element; progress bars are read-only indicators.
- In place of steppers or tabs for user-navigable multi-step flows.
- For indeterminate states when a simple spinner is sufficient and no semantic color is needed.
Colors are flexible and may be selected based on the desired semantic emphasis. The following are available options with recommended contexts:
| Color | Recommended Context |
|---|
| Red/Navy | Neutral, general, or primary progress |
| Green | Positive, successful, or completion progress |
| Yellow | Caution, attention needed, or in-progress warning |
| Destructive Red | Progress tied to potentially irreversible actions |
| Element | Description |
|---|
| Label | Percentage text displayed to the right of the bar. |
| Track | Full background bar; light gray color with dotted pattern or solid light gray on unfilled portion. |
| Fill | Colored pill-shaped portion that grows to represent progress. |
| Size | Description | Visual Indicators |
|---|
| Large | Prominent, higher visibility | Thick pill shaped fill, light gray dotted track |
| Small | Compact, space-efficient | Thin line fill, light gray solid track |
| State | Description | Visual Indicators |
|---|
| Determinate | Known progress value | Fill grows smoothly to percentage |
| Indeterminate | Unknown duration | Continuous flowing or pulsing animation in fill |
| Complete | 100% reached | Full fill in selected color |
| Error | Task failed | Fill in appropriate danger color |
- Always display a visible percentage label (e.g., “50%”) to the right of the bar.
- Round to whole numbers unless higher precision is required.
- Use locale-aware formatting for numbers and symbols.
- Do not use vague labels; percentage provides clear, scannable status.
- Use
role="progressbar" with aria-valuemin="0", aria-valuemax="100", and aria-valuenow="[current]" for determinate states.
- For indeterminate: omit
aria-valuenow and ensure animation is visible; optionally add aria-busy="true".
- Associate the percentage label via
aria-labelledby or ensure visible text is sufficient.
- Maintain ≥4.5:1 contrast for track, fill, and label text against background.
- Announce significant changes (e.g., completion, error) via
aria-live="polite" or "assertive".
Support standard keyboard navigation
Progress bars are non-interactive indicators and should not be focusable. No keyboard interaction required.
