Feedback and status

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>
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 progress element, 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.

Canonical

Minimal progress bar

Rendered from the canonical pattern file.

Exporting audit log 420 of 1,000 records
42%
Preparing search index Total not yet known
Preparing
HTML · Minimal progress bar Raw HTML for HTML · Minimal progress bar
<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

Scenario

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.

Uploading contracts.zip Complete: 24.6 of 24.6 MB
100%
HTML · Completed upload Raw HTML for HTML · Completed upload
<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.

Scenario

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

Validate file Done
Done
Write records 3,120 of 8,000
39%
Rebuild search index Waiting
Waiting
HTML · Multi-stage import Raw HTML for HTML · Multi-stage import
<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.

Scenario

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.

Sending statements 610 of 1,000 confirmed (40 re-queued after timeout)
61%
HTML · Progress revised downward Raw HTML for HTML · Progress revised downward
<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 example

Mobile backup

A long label and value at phone width.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile backup Raw HTML for HTML · Mobile backup
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
valueprogressnumber from 0 to maxabsent (indeterminate)The authoritative amount done. Omit it for the indeterminate state.
maxprogresspositive number1The total. Use the real unit (records, bytes) so value and header text agree.
aria-labelledbyprogressid of .forma-progress__label—Names the progressbar from the visible label.
id.forma-progress__labelunique id—Target for aria-labelledby.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-progressBlock class—Root grid stacking the header above the bar.
.forma-progress__barElement class—The native progress element: full width, 0.65rem tall, with the accent color.
.forma-progress__headerElement class—Wrapping flex row with the label at the start and the value at the end.
.forma-progress__labelElement class—Bold label naming the task. Referenced by the bar's aria-labelledby.
.forma-progress__valueElement class—Secondary, monospace text stating the amount in words or numbers.
Keyboard interaction
KeysResult
—Not focusable and not interactive. Screen readers expose it as a progressbar with its value.
Events
EventDescription
—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

Progress bar states
StateHow it is expressedPresentation
Determinatevalue and max setThe bar fills to value/max immediately on each update, with no interpolation.
Completevalue equals maxFull bar. State completion in the header text too.
Indeterminateno value attributeBrowser-owned activity presentation. The header value must say the total is not yet known.
Decreasedvalue set lower than beforeShown truthfully; nothing hides or smooths the reduction.

Accessibility

Forma provides

  • Uses the native progress element, 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-labelledby or a label element.
  • Update the header text together with value so they never disagree.
  • Only set value equal to max when 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 progress rendering; 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.