VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Progress bar
<forma-progress-bar>
Native determinate progress projected directly from the authoritative value (never overshoots), plus a browser-owned indeterminate variant with explicit text.
- Authoring tag
<forma-progress-bar>- Category
- Feedback and status
- Behavior owner
- Native HTML
- Canonical source
patterns/progress-bar.html
Purpose
A progress bar shows how far a task has got, using the native progress element. Forma adds a header with a label and a textual value, and sizes the bar. The application supplies value and max as it receives them; the bar renders that value immediately with no transition, so it never shows more progress than the application reported. When the total is unknown, omitting value gives the browser's indeterminate bar and the header text says so.
Use when
- The application can count completed work against a known total: records, files, bytes or steps.
- A long operation needs to show that it is advancing and roughly how much remains.
- Work starts with an unknown total that becomes known later; the same element switches from indeterminate to determinate.
Avoid when
- Nothing is known about the amount of work: use Spinner, or keep the indeterminate variant with explicit text.
- The value is a measurement against a range (disk usage, a score), not task completion: use Measure.
- Progress through a questionnaire or a multi-step form: use Survey progress or Steps.
Behavior to know
- The bar is the native
progresselement, so role, value and range come from the platform. - No transition or animation is declared on the determinate bar: a decrease after reconciliation is shown as a decrease.
- The header value is text ("420 of 1,000 records"), so the amount is available without reading the bar.
Basic example
The smallest correct markup: the canonical pattern from patterns/progress-bar.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal progress bar
Rendered from the canonical pattern file.
<forma-progress-bar class="forma-component-tag">
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="export-progress-label">Exporting audit log</span>
<span class="forma-progress__value">420 of 1,000 records</span>
</div>
<progress class="forma-progress__bar" value="420" max="1000" aria-labelledby="export-progress-label">42%</progress>
</div>
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="index-progress-label">Preparing search index</span>
<span class="forma-progress__value">Total not yet known</span>
</div>
<progress class="forma-progress__bar" aria-labelledby="index-progress-label">Preparing</progress>
</div>
</forma-progress-bar>
Click or tap the code once to select all of it, then copy.
Examples
Completed upload
A determinate bar at its maximum. The header value states completion in words, so the finished state does not depend on the bar being full.
<forma-progress-bar class="forma-component-tag">
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-upload-complete-label">Uploading contracts.zip</span>
<span class="forma-progress__value">Complete: 24.6 of 24.6 MB</span>
</div>
<progress class="forma-progress__bar" value="24.6" max="24.6" aria-labelledby="progress-bar-upload-complete-label">100%</progress>
</div>
</forma-progress-bar>
Click or tap the code once to select all of it, then copy.
Multi-stage import
Three bars for the stages of an import in a Stack: a finished stage, one in progress, and one waiting. The waiting stage has value="0", which is determinate and empty, not indeterminate.
Importing customer records
<forma-progress-bar class="forma-component-tag">
<section class="forma-stack" aria-labelledby="progress-bar-import-stages-title">
<h3 id="progress-bar-import-stages-title">Importing customer records</h3>
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-import-stages-validate">Validate file</span>
<span class="forma-progress__value">Done</span>
</div>
<progress class="forma-progress__bar" value="1" max="1" aria-labelledby="progress-bar-import-stages-validate">Done</progress>
</div>
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-import-stages-write">Write records</span>
<span class="forma-progress__value">3,120 of 8,000</span>
</div>
<progress class="forma-progress__bar" value="3120" max="8000" aria-labelledby="progress-bar-import-stages-write">39%</progress>
</div>
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-import-stages-index">Rebuild search index</span>
<span class="forma-progress__value">Waiting</span>
</div>
<progress class="forma-progress__bar" value="0" max="1" aria-labelledby="progress-bar-import-stages-index">Waiting</progress>
</div>
</section>
</forma-progress-bar>
Click or tap the code once to select all of it, then copy.
Progress revised downward
After a retry, the application reports fewer confirmed records than before. The bar is set to the lower authoritative value and the header explains why, instead of holding the earlier, higher figure.
<forma-progress-bar class="forma-component-tag">
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-reconciled-decrease-label">Sending statements</span>
<span class="forma-progress__value">610 of 1,000 confirmed (40 re-queued after timeout)</span>
</div>
<progress class="forma-progress__bar" value="610" max="1000" aria-labelledby="progress-bar-reconciled-decrease-label">61%</progress>
</div>
</forma-progress-bar>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile backup
A long label and value at phone width.
What changes at narrow widths
- The header is a wrapping flex row: when label and value do not fit on one line, the value moves below the label.
- The bar always fills the full width of the component, so small increments stay visible on narrow screens.
- Nothing scrolls horizontally at 320px; long labels wrap.
- The bar has no touch interaction; any Pause or Cancel control is a separate button.
<forma-progress-bar class="forma-component-tag">
<div class="forma-progress">
<div class="forma-progress__header">
<span class="forma-progress__label" id="progress-bar-mobile-backup-label">Backing up the shared finance workspace</span>
<span class="forma-progress__value">1.2 of 3.8 GB</span>
</div>
<progress class="forma-progress__bar" value="1.2" max="3.8" aria-labelledby="progress-bar-mobile-backup-label">32%</progress>
</div>
</forma-progress-bar>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
value | progress | number from 0 to max | absent (indeterminate) | The authoritative amount done. Omit it for the indeterminate state. |
max | progress | positive number | 1 | The total. Use the real unit (records, bytes) so value and header text agree. |
aria-labelledby | progress | id of .forma-progress__label | — | Names the progressbar from the visible label. |
id | .forma-progress__label | unique id | — | Target for aria-labelledby. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-progress | Block class | — | Root grid stacking the header above the bar. |
.forma-progress__bar | Element class | — | The native progress element: full width, 0.65rem tall, with the accent color. |
.forma-progress__header | Element class | — | Wrapping flex row with the label at the start and the value at the end. |
.forma-progress__label | Element class | — | Bold label naming the task. Referenced by the bar's aria-labelledby. |
.forma-progress__value | Element class | — | Secondary, monospace text stating the amount in words or numbers. |
| Keys | Result |
|---|---|
| — | Not focusable and not interactive. Screen readers expose it as a progressbar with its value. |
| Event | Description |
|---|---|
— | None. The application sets the value property as updates arrive. |
Form behavior
The progress element does not submit a value or take part in form validation.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Determinate | value and max set | The bar fills to value/max immediately on each update, with no interpolation. |
| Complete | value equals max | Full bar. State completion in the header text too. |
| Indeterminate | no value attribute | Browser-owned activity presentation. The header value must say the total is not yet known. |
| Decreased | value set lower than before | Shown truthfully; nothing hides or smooths the reduction. |
Accessibility
Forma provides
- Uses the native
progresselement, so its role and current value are exposed by the platform. - Places the amount in visible text as well as in the bar.
- Keeps the bar visible in forced colors by relying on the native element's system rendering.
Your application supplies
- Label every bar through
aria-labelledbyor alabelelement. - Update the header text together with
valueso they never disagree. - Only set
valueequal tomaxwhen the application has confirmed completion. - If progress changes should be announced, put a short summary in a separate
role="status"region at sensible intervals; the bar itself is not a live region.
Responsive behavior
- The bar is 100% of the component's width at every size.
- The header wraps: label and value sit on one line when they fit and stack otherwise.
- No breakpoints; place several bars in a Stack for multi-stage work.
Motion
- No animation on the determinate bar: each new value is placed immediately, so the bar cannot lag behind or overshoot the reported value.
- The indeterminate bar's activity animation belongs to the browser's native
progressrendering; Forma does not add or change it. - Reduced-motion preferences therefore need no special handling for determinate progress.
Usage guidance
Do
- Express the value in the user's unit ("420 of 1,000 records").
- Switch from indeterminate to determinate as soon as the total is known.
Avoid
- Faking progress with a timer that is not tied to real work.
- Adding a CSS transition to the bar, which could show more progress than has happened.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.