ProgressBar
A ProgressBar communicates how far along a process is. It renders a single horizontal track with a fill that advances from 0 to 100.
Overview
When to use
- To show progress through a multi-step process (payments made, tasks completed).
- To give feedback on loading or upload operations.
When not to use
- To represent a rating or score — use a dedicated rating component.
- For indeterminate loading where the total is unknown — a spinner is more appropriate (indeterminate state planned for a future iteration).
Values
The value prop accepts any number from 0 to 100. Values outside this range are clamped automatically. The fill animates via transform: translateX to avoid layout reflow on every change.
With Label
The ProgressBar renders only the track. Labels, counts, and percentage text are the responsibility of the parent — this keeps the component generic and reusable across contexts.
Accessibility
The component sets role="progressbar", aria-valuenow, aria-valuemin={0}, and aria-valuemax={100} on the root element. Screen readers will announce the current progress value automatically.
To give screen readers a meaningful label, pass aria-label or aria-labelledby:
<ProgressBar value={60} aria-label="File upload progress" />
Controls
Interactive controls are available in Storybook. Open Storybook
Props
Token mapping
| Property | Token |
|---|---|
| track background | --color-bg-page |
| fill color | pending tokenization |
| bevel (top-left outer) | --sunken-outer-dark |
| bevel (bottom-right outer) | --sunken-outer-light |
| bevel (top-left inner) | --sunken-inner-dark |
| bevel (bottom-right inner) | --sunken-inner-light |
Changelog
| Date | Change |
|---|---|
| 2026-03-23 | Migrated to Tailwind; replaced app-specific props (paidCount, totalCount, percentage) with generic value; moved meta row to consumer; added ARIA attributes; added stories and documentation |
| 2026-03-15 | Initial component created |