Progress

Demos

A labelled bar with a percentage.

Analysing your panel

"use client"

import * as React from "react"

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

export function ProgressDemo() {
  const [value, setValue] = React.useState(20)

  React.useEffect(() => {
    const timer = setTimeout(() => setValue(66), 500)
    return () => clearTimeout(timer)
  }, [])

  return (
    <Progress value={value} className="w-full max-w-sm">
      <ProgressLabel>Analysing your panel</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}

Usage

Use a progress bar when a task takes more than a second and you know how much is left: an upload, an analysis, an onboarding flow. Set value to null when you cannot tell how long it will take.

Import it from @workspace/ui/components/progress.

Anatomy

Progress — The root. Renders the track and indicator for you.
ProgressLabel — Names the task. Read by screen readers.
ProgressValue — Shows the current value. Defaults to a percentage.
ProgressTrack and ProgressIndicator — The bar and its fill. Progress renders them for you, so do not add them as children.

Notes

Without a ProgressLabel, give the root an aria-label.
Pass a function as the child of ProgressValue to format the text. It gets the formatted value and the raw value, so you can show "4 of 6 steps".
Do not use a progress bar to show a health score. It reads as a task, not a measurement.

Examples

Custom value

Set max and pass a function to ProgressValue to show steps instead of a percentage.

Onboarding

"use client"

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

export function ProgressCustomValue() {
  return (
    <Progress value={4} max={6} className="w-full max-w-sm">
      <ProgressLabel>Onboarding</ProgressLabel>
      <ProgressValue>{(_, value) => `${value} of 6 steps`}</ProgressValue>
    </Progress>
  )
}

Without label

A bar on its own. Give it an aria-label.

"use client"

import { Progress } from "@workspace/ui/components/progress"

export function ProgressWithoutLabel() {
  return <Progress value={40} aria-label="Profile complete" className="w-full max-w-sm" />
}

Indeterminate

Set value={null} when the duration is unknown. The fill shrinks to a third of the track and pulses.

"use client"

import { Progress } from "@workspace/ui/components/progress"

export function ProgressIndeterminate() {
  return <Progress value={null} aria-label="Uploading" className="w-full max-w-sm" />
}

Props

These are the props you set most often. Unlisted props pass through to the underlying element.

Progress

Prop	Type	Default	Description
`value`	`number or null`	—	Required. Current value. `null` is indeterminate.
`min`	`number`	`0`	Lowest value.
`max`	`number`	`100`	Highest value.
`format`	`Intl.NumberFormatOptions`	—	Formats the text in ProgressValue.
`className`	`string`	—	Classes merged onto the root.