progress

Displays the completion progress of a task. Use for file uploads, form steps, loading states, or any operation with a known endpoint. For scalar measurements (like disk space), use meter instead.

When to Use

  • File upload progress
  • Download progress
  • Multi-step form completion
  • Loading states with known duration
  • Installation or setup progress

Use meter instead for static measurements like disk usage, battery level, or scores.

Basic Usage

A determinate progress bar shows completion percentage.

Attributes

Attribute Purpose Default
value Current progress value Indeterminate if omitted
max Maximum value (completion) 1

Indeterminate Progress

Omit the value attribute for tasks with unknown duration. Shows an animated loading state.

Size Variants

Different heights for various contexts.

Color Variants

Semantic colors for different states or contexts.

Labeled Progress

Use the .labeled wrapper pattern for progress bars with percentage displays.

Recipes

Reading Progress Indicator

A fixed-position progress bar at the top of the page that tracks scroll position. Uses a single passive scroll listener and one attribute update.

Indeterminate as Skeleton Shimmer

An indeterminate <progress> (no value attribute) triggers the browser's native animation. Override the pseudo-element backgrounds for a shimmer effect — zero JS, zero extra DOM. See the skeleton loading pattern for the full approach using data-loading="skeleton".

Ring Mode

Add data-type="ring" to render a circular progress indicator. Without JavaScript, it renders as a standard linear bar (progressive enhancement). With JS, the progress-ring-init utility enhances it to a circle with an auto-synced center label.

Ring Sizes

Use data-size for different ring diameters.

Ring Colors

Semantic color classes work on rings the same as linear bars.

Ring Indeterminate

Omit value for a spinning animation. No extra attributes needed — native indeterminate state is detected automatically.

Custom Labels

By default, the center label shows the percentage. Use data-label to override it, or data-label="none" to hide it.

Ring Attributes

Attribute Values Description
data-type="ring" ring Enables circular mode
data-size xs, s, m, l, xl Ring diameter (default: m)
data-label text or none Override or hide center label

Ring Custom Properties

Property Default Description
--progress-ring-size 4em Ring diameter
--progress-ring-width 0.35em Track thickness

Updating with JavaScript

Just set the native value property — the JS utility auto-syncs the --progress custom property and center label via MutationObserver.

Related

  • meter — For scalar measurements (not progress)
  • output — Display progress values dynamically
  • label — Label for the progress element
↑