Progress Bar

Anatomy

Options

Progress states

Use determinate progress only when a meaningful completion value is available. An indeterminate indicator has no numeric percentage.

Variants

A variant changes appearance; it does not mark a task complete, pause it or report an error automatically. Update the label and surrounding message to explain the task state.

Sizes

Container scaling

Use the Scale switch beside Light/Dark in the preview above, or set data-scale="small|medium|large" on a containing element. Font size, line height, spacing and radii inherit that context. A local size="sm" remains smaller within the chosen context; it does not cancel the container scale. Track/indicator dimensions and border widths keep their existing local-size behavior.

The default context is medium. Nested containers can replace the inherited context explicitly, without multiplying the parent context again. Brand and light/dark mode remain independent. The current adopters are Status Light, Meter and Progress Bar; existing components have not been migrated implicitly.

Table of options

Custom Element booleans are enabled by attribute presence. Omit show-value or indeterminate to turn them off; writing indeterminate="false" still enables it. Macro booleans use actual true/false arguments.

Behaviors

Switch from unknown progress by removing indeterminate and setting a finite value. At 100 the component remains visible; the consuming workflow decides when to replace it with a completion message. It does not emit completion events or remove itself.

Usage guidelines

Keep cancellation and retry controls outside the progressbar. Use a nearby message to explain failures; a negative fill alone is not an error explanation.

Content standards

• Use task-specific wording, such as “Uploading photos” or “Preparing download”.
• Keep the label stable while the percentage changes.
• Do not promise a remaining duration unless the application can estimate it reliably.
• For completion or failure, provide a clear outcome in nearby text.

Keyboard interactions

Progress Bar has no keyboard commands and does not enter the tab order. Related cancel, retry or navigation actions need separate buttons or links.

Accessibility

• The root has role="progressbar" and a task name supplied through aria-label.
• Determinate progress exposes aria-valuemin="0", aria-valuemax="100" and aria-valuenow.
• Indeterminate progress omits aria-valuenow and the visible numeric percentage.
• A progressbar is not an automatic live region. If completion must be announced, use a separate, appropriately timed status message rather than announcing every percentage change.
• Reduced-motion preference disables the indeterminate animation.

Implementation

import "ui-foundations/elements/ui-progress-bar";

<uif-progress-bar id="upload-progress" value="0"
  label="Uploading photos" show-value></uif-progress-bar>

const progress = document.querySelector("#upload-progress");
progress.setAttribute("value", "60");

// Unknown work amount: no percentage is exposed.
progress.setAttribute("indeterminate", "");

// Resume known progress.
progress.removeAttribute("indeterminate");
progress.setAttribute("value", "75");

For static HTML without Custom Element JavaScript:

{% import "macros/ui.njk" as uif %}
{{ uif.progressBar(value=0, label="Uploading photos", showValue=true) }}
{{ uif.progressBar(label="Preparing download", indeterminate=true) }}

The macro emits the progressbar, optional header and styled track/fill. Pass finite numbers or an empty value to the macro. Both interfaces use the same CSS pattern; changes to static markup must keep its fill value and accessible current value aligned.

The scale belongs to the container, not to the component's size attribute:

<div data-scale="large">
  <uif-progress-bar size="sm" label="Uploading" value="60"></uif-progress-bar>
</div>

Theming

Use the brand and mode switches in the preview above. Visual values come from the pattern's --uif-progress-bar-* slots and existing Semantic roles. Labels use semantic content color. An inward outline keeps colored markers or fills discernible across light and dark surfaces.

Set data-brand="a", "b" or "c" and data-mode="light" or "dark" on the root element. Consumers own activation of these contexts. See Design Tokens.

Tokens

Use container scale and local size for typography and spacing. The table lists component overrides.

Design checklist

The browser checks cover specific Runtime behavior and contrast pairs; they do not certify complete accessibility or live design parity.