Skip to content
opsinjs
Edit this page

Components

Progress

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.

Usage

pnpm dlx shadcn@latest add @opsinjs/progress

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Progress } from "@/components/ui/progress"
<Progress label="Uploading photos" value={45} />

Examples

Theme
Density
Text
Status
Accent theme
Accent
progress · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
progress-a-task-completing · base base · style base-lyraOpen under the product theme
progress-a-task-completing.tsx
import { Progress } from "@/components/ui/progress"

export default function ProgressATaskCompleting() {
  return (
    <div className="w-full max-w-sm">
      <Progress label="Uploading 3 photos" value={45} />
    </div>
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
progress-indeterminate · base base · style base-lyraOpen under the product theme
progress-indeterminate.tsx
import { Progress } from "@/components/ui/progress"

export default function ProgressIndeterminate() {
  return (
    <div className="w-full max-w-sm">
      <Progress label="Preparing your export" value={null} />
    </div>
  )
}

When to use it

Use it when

  • 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.
  • Tracking a multi-step flow, such as step three of five, by passing the step count as value and the total as max.
  • Signalling that a task with no known shape is running, by passing value={null}, rather than inventing a percentage.

Do not use it when

  • You are drawing a health reading against a range. A bar implies a target the reading does not have and carries no reference bounds.Use range-bar instead.
  • 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.Use score-dial instead.
  • 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.Use skeleton instead.

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.
KeyActionNotes
TabSkips the barNot a control. Nothing is focusable, so a keyboard user pays no tab stop.
Shift+TabSkips the barSame in reverse. The bar never appears in the focus order.
Arrow keysNothingNothing to select, move or change. The product sets the value.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from ProgressProps in registry/bases/base/progress.tsx.

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.