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.

70% 60%

Code

<label>Upload Progress</label> <progress value="70" max="100">70%</progress> <label>Step 3 of 5</label> <progress value="3" max="5">60%</progress>

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.

Loading...

Code

<!-- No value attribute = indeterminate --> <progress>Loading...</progress>

Size Variants

Different heights for various contexts.

60% 60% 60% 60%

Code

<progress class="xs" value="60" max="100">60%</progress> <progress class="s" value="60" max="100">60%</progress> <progress value="60" max="100">60%</progress> <!-- default --> <progress class="l" value="60" max="100">60%</progress>

Color Variants

Semantic colors for different states or contexts.

70% 100% 60% 30%

Code

<progress value="100" max="100">Complete</progress> <progress class="success" value="100" max="100">Complete</progress> <progress class="warning" value="60" max="100">60%</progress> <progress class="error" value="30" max="100">30%</progress>

Labeled Progress

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

45%
78%

Code

<div class="labeled"> <label> <span>Uploading file.zip</span> <span>45%</span> </label> <progress value="45" max="100">45%</progress> </div>

With Output Element

Use output to display dynamic progress values.

65%

Code

<label>Progress: <output id="progress-value">65%</output></label> <progress value="65" max="100">65%</progress>

Real-World Examples

File Upload

67%

Multi-Step Form

50%

Course Progress

60%

Loading State (Indeterminate)

Connecting...

Progress vs Meter

Use progress Use meter
Tasks in progress Static measurements
File uploads, downloads Disk space, battery level
Has determinate/indeterminate states Has optimum value ranges
Value changes over time Value is a snapshot
No color change based on value Color changes based on optimum

Accessibility Notes

  • Include fallback text: Content between tags is shown if progress is not supported
  • Use labels: Always associate a label with the progress element
  • Announce updates: Consider using aria-live for important progress updates
  • Provide context: Include percentage or step numbers in visible text
  • Screen reader support: Progress elements are announced as "X% complete"

CSS Reference

progress { appearance: none; display: block; inline-size: 100%; block-size: var(--size-s); border: none; border-radius: var(--radius-full); overflow: hidden; background: var(--color-surface-raised); } /* WebKit/Blink progress bar */ progress::-webkit-progress-bar { background: var(--color-surface-raised); border-radius: var(--radius-full); } progress::-webkit-progress-value { background: var(--color-interactive); border-radius: var(--radius-full); transition: inline-size var(--duration-normal) var(--ease-out); } /* Firefox */ progress::-moz-progress-bar { background: var(--color-interactive); border-radius: var(--radius-full); } /* Size variants */ progress.xs { block-size: var(--size-3xs); } progress.s { block-size: var(--size-2xs); } progress.m { block-size: var(--size-s); } progress.l { block-size: var(--size-m); } /* Color variants */ progress.success::-webkit-progress-value { background: oklch(60% 0.18 145); } progress.warning::-webkit-progress-value { background: oklch(75% 0.18 75); } progress.error::-webkit-progress-value { background: oklch(55% 0.2 25); } /* Indeterminate animation */ progress:indeterminate { animation: progress-indeterminate 1.5s ease-in-out infinite; }

Related Elements

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