Progress indicators
Native progress bars and decorative spinners for loading states.
When to use
Use progress indicators while work is running. Choose a determinate progress bar for measurable completion, an indeterminate bar or spinner when the duration is unknown, and a Skeleton when the final layout can be reserved.
Determinate progress
Use a labelled native <progress> when completion can be measured. Keep value, max and any visible value text synchronized in application code.
<label for="upload-progress">Uploading files</label>
<progress class="progress" id="upload-progress" max="100" value="64">64%</progress>The native element supplies progressbar semantics and its current value. Do not add role="progressbar" or duplicate aria-valuenow.
Indeterminate progress
Omit value when an operation is active but its completion cannot be measured. A missing value is different from value="0".
<label for="sync-progress">Synchronizing workspace</label>
<progress class="progress progress-secondary" id="sync-progress" max="100">Synchronizing…</progress>To switch an existing progress bar to indeterminate, remove its value attribute and property state. Reduced-motion preferences keep a static value segment instead of moving it.
Spinner
Use a spinner for a short operation when neither a percentage nor final content geometry is known. The spinner is decorative: hide it from assistive technology and put the loading message in a separate status.
<div class="d-flex align-items-center gap-2" role="status">
<span class="spinner" aria-hidden="true"></span>
<span>Saving changes…</span>
</div>Do not give the decorative element a progressbar role. Keep the text visible when possible; if an existing labelled control already communicates the state, avoid adding another live announcement.
Sizes and layouts
Use -sm, -md or -lg sizes. Progress bars are block-width by default; .progress-inline uses --progress-inline-size. Spinners are inline by default; .spinner-block establishes a block layout.
Semantic colors
Color supports context but must not be the only status cue. Keep the label or adjacent status text meaningful.
Choosing a loading pattern
- Use
progressfor measurable completion, or its indeterminate state when the same operation temporarily has no usable estimate. - Use a
spinnerfor short, compact activity without known content geometry. - Use a Skeleton when placeholders can reserve the final content geometry and prevent layout shift.
- Expose one loading status per operation. Do not combine progress, a spinner and a skeleton in a way that announces the same state more than once.
Accessibility and behavior
- Name native progress elements through a label and keep value text synchronized with
valueandmax. Omitvaluefor indeterminate work. - Keep spinners decorative and expose one useful loading status per operation. Do not announce every percentage change through a live region.
- Application code updates progress and completion states. Keep loading text meaningful when motion or visual color cues are unavailable.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--progress-block-size | 0.5rem | Progress bar thickness. | .progress |
--progress-inline-size | 8rem | Width of the inline variant. | .progress |
--progress-track-color | var(--bg-active) | Unfilled track color. | .progress |
--progress-value-color | var(--primary) | Filled progress color. | .progress |
--progress-border-color | var(--control-border-color) | Border color. | .progress |
--progress-border-width | var(--border-width) | Border thickness. | .progress |
--progress-border-radius | 9999px | Corner radius. | .progress |
--progress-animation-duration | 1.5s | Duration of indeterminate cycles and value transitions. | .progress |
--progress-animation-easing | ease-in-out | Timing curve for indeterminate cycles and value transitions. | .progress |
--spinner-size | 1rem | Width and height. | .spinner |
--spinner-border-width | 0.125rem | Border thickness. | .spinner |
--spinner-track-color | color-mix(in srgb, var(--spinner-color) 25%, transparent) | Muted ring color. | .spinner |
--spinner-color | var(--primary) | Highlighted ring segment color. | .spinner |
--spinner-animation-duration | 0.75s | Duration of one animation cycle. | .spinner |
--spinner-animation-easing | linear | Timing curve of the animation. | .spinner |