Progress

A horizontal progress bar for conveying determinate completion status. Built on the @base-ui/react Progress primitive with composable ProgressLabel and ProgressValue sub-components for contextual display.

Anatomy

<Progress> is the root wrapper that accepts a value prop (0–100). ProgressTrack provides the background rail and ProgressIndicator fills it. Optional ProgressLabel and ProgressValue sit outside the track.

x
Progress (value=60)ProgressTrackProgressIndicator

Examples

Pass any integer 0–100 to value to control fill amount.

value=25
x

25% — early stage

value=60
x

60% — in progress

value=100
x

100% — complete

With Label and Value

ProgressLabel provides a semantic text description and ProgressValue displays the numeric percentage. Both are flex siblings of ProgressTrack inside the root.

Label only

Uploading files…
x

Label + Value

Profile completion
x

Storage quota example

Storage used
x

States

Empty (0%)

x

Mid (50%)

x

Complete (100%)

x

Design Guidelines

Do

  • Pair with a label for context. A bare progress bar without a label leaves users guessing what is progressing.
  • Show the value when precision matters. Use ProgressValue for uploads, installs, and quota scenarios.
  • Use for determinate progress only. You must know the total — otherwise use Spinner.

Don't

  • Don't use for indeterminate loading. If you don't know the duration or percentage, use a Spinner instead.
  • Don't animate fake progress. Simulating progress where none exists erodes user trust.
  • Don't omit the track. ProgressTrack provides the background rail — rendering the indicator alone breaks the visual.

Developer Reference

Accessibility

  • Built on Base UI Progress primitive — sets role="progressbar", aria-valuenow, aria-valuemin, and aria-valuemax automatically.
  • ProgressLabelis linked to the progressbar via the primitive's labelling mechanism.
  • ProgressValue renders a tabular-nums percentage with ml-auto for right-alignment.
  • The indicator uses transition-all for smooth fills on value updates.

Usage

import {
  Progress,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress"

// Basic
<Progress value={60}>
  <ProgressTrack>
    <ProgressIndicator />
  </ProgressTrack>
</Progress>

// With label
<Progress value={45}>
  <ProgressLabel>Uploading files…</ProgressLabel>
  <ProgressTrack>
    <ProgressIndicator />
  </ProgressTrack>
</Progress>

// With label and value percentage
<Progress value={72}>
  <ProgressLabel>Profile completion</ProgressLabel>
  <ProgressValue />
  <ProgressTrack>
    <ProgressIndicator />
  </ProgressTrack>
</Progress>