---
title: "Progress"
description: "A bar for how far through a task or a set of steps the reader has got, built on Base UI Progress and never used to draw a health value."
url: "https://opsinjs.pensievelabs.org/docs/components/progress"
source: "https://opsinjs.pensievelabs.org/docs/components/progress.md"
section: "Components"
status: "shipped"
kind: "component"
category: "feedback"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["progress bar", "completion"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="progress"
  status="shipped"
  questions="[
  &#x22;Nobody has listened to the bar in a screen reader, so whether label, then value, then busy state lands as a hearing reader expects is reasoned, not heard.&#x22;,
  &#x22;Under prefers-reduced-motion the indeterminate pulse is dropped, and whether a full static fill reads as running rather than done has not been checked with a reader who turns motion off.&#x22;,
  &#x22;Under forced colours the muted track and the accent fill are both replaced by the platform's pair, and whether the fill stays distinct from the track is untested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="progress" unbuilt="false" importPath="@/components/ui/progress" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { Progress } from "@/components/ui/progress"
```

```tsx
<Progress label="Uploading photos" value={45} />
```

## Examples [#examples]

<ComponentPreview name="progress" />

### A task completing [#a-task-completing]

A fictional upload part way done. `value` sets the fill, and the readout writes
the same figure beside it for a reader who cannot use the fill.

<ComponentPreview name="progress-a-task-completing" kind="example" align="start" />

### An indeterminate task [#an-indeterminate-task]

`value={null}` for a task with no known shape. The fill spans the track and
pulses, the readout says the work is in progress, and Base UI drops
`aria-valuenow` so a screen reader announces a busy state.

<ComponentPreview name="progress-indeterminate" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Showing how far through an upload or a download the reader has got, where the amount done is a real fraction of a known whole.&#x22;,
  &#x22;Tracking a multi-step flow, such as step three of five, by passing the step count as value and the total as max.&#x22;,
  &#x22;Signalling that a task with no known shape is running, by passing value={null}, rather than inventing a percentage.&#x22;,
]"
  avoid="[
  { case: &#x22;You are drawing a health reading against a range. A bar implies a target the reading does not have and carries no reference bounds.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;You are showing a composite score. A bar reads it as a mark out of its top, the one reading a score must not invite.&#x22;, instead: &#x22;score-dial&#x22; },
  { case: &#x22;The wait has no bar-shaped answer, because you cannot say what is arriving as a fraction. A placeholder of the shape to come says more.&#x22;, instead: &#x22;skeleton&#x22; },
]"
/>

## Accessibility [#accessibility]

`aria-valuenow` carries the amount done, with the label, minimum and maximum.
Nothing takes focus, so the bar costs no tab stop. The transition and pulse drop
under `prefers-reduced-motion`, and words carry the state. Type steps and the
`em` track height scale together, so 200% text grows the bar rather than
clipping it. `pnpm run check:a11y` confirms on every commit that colour is a
role token on neither axis and that no type size is in `px`.

The audit made three fixes: a plain `aria-label` on the root so the name
survives a first paint before Base UI's own wiring runs, a sibling status region
announcing `"{label} complete."` at max, and `aria-hidden` on the indeterminate
branch's text to match the determinate readout.

**Residual items.**

* Fill contrast against the track is not measured, and the report below carries
  it until it is.
* Wrap for a long label and print output were not checked.

<KeyboardTable
  name="progress"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the bar&#x22;,
    notes: &#x22;Not a control. Nothing is focusable, so a keyboard user pays no tab stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the bar&#x22;,
    notes: &#x22;Same in reverse. The bar never appears in the focus order.&#x22;,
  },
  {
    keys: &#x22;Arrow keys&#x22;,
    action: &#x22;Nothing&#x22;,
    notes: &#x22;Nothing to select, move or change. The product sets the value.&#x22;,
  },
]"
/>

<ContrastReport component="progress" />

## Props interface [#props-interface]

<PropsTable name="ProgressProps" />

`value={null}` is a different state from `value={0}`: `null` draws the running
state and 0 a task not started. A value outside 0 to `max` is clamped by Base UI
and raises a development warning. No colour prop exists, and `className` takes
neither a status nor a category tint.
