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.

64%

HTML
<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".

Synchronizing…

HTML
<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.

Saving changes…
HTML
<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.

Small

35%

Medium

55%

Large

75%

45%

Semantic colors

Color supports context but must not be the only status cue. Keep the label or adjacent status text meaningful.

72%

72%

72%

72%

72%

Choosing a loading pattern

  • Use progress for measurable completion, or its indeterminate state when the same operation temporarily has no usable estimate.
  • Use a spinner for 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 value and max. Omit value for 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.

TokenDefaultPurposeScope / state
--progress-block-size0.5remProgress bar thickness..progress
--progress-inline-size8remWidth of the inline variant..progress
--progress-track-colorvar(--bg-active)Unfilled track color..progress
--progress-value-colorvar(--primary)Filled progress color..progress
--progress-border-colorvar(--control-border-color)Border color..progress
--progress-border-widthvar(--border-width)Border thickness..progress
--progress-border-radius9999pxCorner radius..progress
--progress-animation-duration1.5sDuration of indeterminate cycles and value transitions..progress
--progress-animation-easingease-in-outTiming curve for indeterminate cycles and value transitions..progress
--spinner-size1remWidth and height..spinner
--spinner-border-width0.125remBorder thickness..spinner
--spinner-track-colorcolor-mix(in srgb, var(--spinner-color) 25%, transparent)Muted ring color..spinner
--spinner-colorvar(--primary)Highlighted ring segment color..spinner
--spinner-animation-duration0.75sDuration of one animation cycle..spinner
--spinner-animation-easinglinearTiming curve of the animation..spinner