Skip to content

Design system

Documentation

DesignComponents / Progress

Components / Progress

Beta

Progress

Show an accessible amount of completed work.

On this page

Examples

Determinate and indeterminate

Use a value when the amount of completed work is known, and null while the duration or total is unknown.

Uploading report65%
Preparing export

Determinate upload and indeterminate export progress

Try the props

Switch between a known amount and an indeterminate task; the displayed number follows the progress value.

Uploading report65%

Progress property playground

When to use

Use Progress when a task has a useful measurable range. Use null for an indeterminate task. Progress only renders presentation; the feature owns task state and update timing.

Usage

import { Progress } from "@phuctech/ui/components/progress";

<Progress label="Uploading report" value={65} showValue />

API

Component API
PropTypeDefaultDescriptionConstraints
valuenumber | null0Current progress, or null when completion is unknown.Finite numbers are clamped to min and max.
minnumber0Lower bound of the progress range.Non-finite values fall back to 0.
maxnumber100Upper bound of the progress range.Must be greater than min; invalid values use min + 100.
labelstring"Progress"Accessible name and optional visible label.Use the task name, not just the word progress.
showValuebooleanfalseDisplays the rounded percentage or an in-progress label.Only show a percentage when the range communicates useful completion.
size"sm" | "md" | "lg""md"Track thickness.Does not change the value range.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-action-primaryCompleted rangeBrand colorProgress remains distinct from the neutral track.
mutedTrackSubtle surfaceSeparates the remaining range in light and dark themes.
motion tokens / reduced motionIndeterminate animation1.4s standard easingStops the moving range when reduced motion is requested.

Accessibility

  • The component exposes progressbar semantics, min/max bounds, and a current value when determinate.
  • It has a task-specific accessible name. Keep textual status nearby when the precise percentage matters.

Do and don’t

Do

Use a stable range and report the same value to the user and the component.

Don’t

Show a made-up percentage when completion cannot be estimated.

  • Spinner indicates an unknown wait.
  • Skeleton reserves the shape of content during loading.