Progress bar
A 6 px track that fills as a task with a known size advances. Show the number next to it; use the indeterminate bar only when you truly cannot measure.
Usage
Use it when
- A task with a measurable amount runs: an upload, an import, a report export, questions answered in a tryout.
- Progress through a course or a module, shown with its number ("12 of 20 lessons").
- A short, unmeasurable preparation step where a line fits better than a spinner (
.progress--indeterminate).
Use something else when
- A compact tile or a score that needs to fit in a square: use Progress ring.
- A level or a capacity, not a task (storage used, password strength): use Meter.
- A short wait with no number, inside a button or a row: use Spinner.
- Content is loading and its layout is known: use Skeleton.
- Long work of unknown length, where elapsed time is the honest signal: use Thinking.
- A file uploading into a drop zone: use Upload progress.
- The steps of a multi-page flow: use Steps.
- Shares of a whole across categories: use Percentage bar.
- A page is loading after navigation: use Nav progress.
Where it goes. Directly under what it measures: in an upload row, in a course card, under the header of a running job. With .progress-meta above it for the label and the number. Full width of its container on every screen size; never as a page-wide strip (that is navigation progress).
Examples
<div class="progress-meta"><span id="up-l">Uploading thesis.pdf</span><b>64%</b></div> <div class="progress" role="progressbar" aria-labelledby="up-l" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64"> <div class="progress__fill" style="transform: scaleX(0.64);"></div> </div>
<div class="card" style="max-width: 360px;">
<div class="card__title">Statistics for beginners</div>
<div class="card__sub">Module 3: sampling</div>
<div style="margin-top: 16px;">
<div class="progress-meta"><span>Lessons</span><b>12 of 20</b></div>
<div class="progress progress--thin" role="progressbar" aria-label="Lessons done" aria-valuemin="0" aria-valuemax="20" aria-valuenow="12" aria-valuetext="12 of 20 lessons"><div class="progress__fill" style="transform: scaleX(0.6);"></div></div>
</div>
</div><div style="max-width: 420px; width: 100%;"> <div class="progress-meta"><span>Preparing your transcript</span><span>Usually under a minute</span></div> <div class="progress progress--thin progress--indeterminate" role="progressbar" aria-label="Preparing your transcript"><div class="progress__fill"></div></div> </div>
<div style="max-width: 420px; width: 100%;"> <div class="progress-meta"><span>Report exported</span><b>Done</b></div> <div class="progress" role="progressbar" aria-label="Report export" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100"><div class="progress__fill" style="transform: scaleX(1); background: var(--success);"></div></div> </div>
Anatomy
| Part | What it is |
|---|---|
.progress | Required. The track: 6 px tall, rounded, on --bg-track. Carries role="progressbar". |
.progress__fill | Required. The fill, a block that scales from the left. Set transform: scaleX(0.64) for 64 %. |
.progress-meta | Optional row above the bar: label on the left, the value in <b> on the right (tabular figures). |
Variants and sizes
| Class or attribute | When |
|---|---|
progress | 6 px. Standalone tasks and uploads. |
progress--thin | 4 px. Inside cards, list rows and tight layouts. |
progress--indeterminate | A 40 % segment sweeps every 1.4 s. Only when the size of the work is unknown. |
progress-meta | Label and value row above the bar. |
States
| State | How |
|---|---|
in progress | transform: scaleX(value) on the fill plus aria-valuenow on the bar. |
indeterminate | .progress--indeterminate and no aria-valuenow. |
done | scaleX(1), optionally background: var(--success) on the fill, and "Done" in the meta. |
failed | Keep the fill where it stopped, color it var(--danger) and put the reason and a retry in an alert or the row. |
Motion and microinteractions
- The fill moves with
transform: scaleX()on--ease-inoutover--d-considered(480 ms): it is already on screen, so it eases both ends. Background color changes over--d-standard. - Because it is a transition, rapid updates retarget smoothly; do not throttle values to make it look busy and never fake progress that stalls at 90 %.
- Indeterminate:
lds-indeterminate, 1.4 s on--ease-inout, infinite. Under reduced motion loops play once, so pair it with words. - Animate
transformonly, neverwidth, so updates stay on the compositor.
Accessibility
role="progressbar"witharia-valuemin,aria-valuemaxandaria-valuenow; name it witharia-labelledbypointing at the meta label, oraria-label.- Use
aria-valuetextwhen the raw number is not the clearest reading ("12 of 20 lessons", "About 2 minutes left"). - Indeterminate bars omit
aria-valuenow. - Do not announce every tick. Announce the end once, with a toast or a
role="status"line.
Do and don't
Do
- Show the number or the count next to the bar.
- Use real progress; if you only know steps, show steps.
- Keep the bar where the result will appear, so attention is already there when it finishes.
Don't
- Animate
widthor use a custom gradient fill. - Use the indeterminate bar for work you can measure.
- Use a progress bar for a value that is not a task (storage, strength): that is a meter.
Behavior and code
Plain HTML. None. Set transform: scaleX() on .progress__fill and aria-valuenow on .progress from your code.