React Progress component

Preview

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

Usage

Use when

Upload and download progress
Percentage of a task finished
How much of a form is filled in
Waits where you know the duration

Avoid when

You cannot say how long — use Loading
Discrete steps — use a stepper
Status with no number — use Badge

Implementation notes

Pass a value when you know the percentage; pass null when you do not
Add a label whenever the bar alone leaves the purpose unclear
warning and danger carry state, not decoration; a finished task says so in words, not in green
tone="neutral" with role="meter" for a magnitude where full is not success
Counted work reads better in words: valueLabel="8 of 10" shows the count and is heard the same way
Values outside min and max are clamped before display
Pass aria-valuetext and aria-label to localise what a screen reader hears

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Tones

Colour carries state only: work in progress, a quota running out, a quota spent.

import { Stack } from '@usefragments/ui';

<Stack direction="column" gap="md">
  <Progress value={75} label="Processing" showValue />
  <Progress value={82} tone="warning" label="Storage nearly full" showValue />
  <Progress value={100} tone="danger" label="Storage full" showValue />

Meter

A reading where hitting the top is not a win, with its value in words.

<Progress
  value={42}
  tone="neutral"
  role="meter"
  label="Seats used"
  valueLabel="42 of 100"

Indeterminate

value={null}: a short run travels the track until the work is counted.

<Progress value={null} label="Counting files" />

API reference

Component props
Prop	Type	Default	Description
`formatValue`	`((value: number) => string) \| undefined`	Not set	Custom formatter for displayed progress value
`label`	`string \| undefined`	Not set	Label text above the progress bar
`max`	`number \| undefined`	`100`	Maximum value
`min`	`number \| undefined`	`0`	Minimum value
`showValue`	`boolean \| undefined`	`false`	Show the value beside the label
`tone`	`ProgressTone \| undefinedwarningdangerneutralaccent`	`accent`	Fill colour. accent is the selection colour of work in progress; neutral is a meter whose maximum is not a verdict; warning and danger carry a quota near or over its limit. A full bar is never a success.
`value`	`number \| null \| undefined`	`null`	Current value, between min and max. Null for work not yet counted.
`valueLabel`	`string \| undefined`	Not set	The value in words, shown beside the label in place of the percentage ("8 of 10", "42 of 100 GB"). Setting it shows the value, and it becomes the value text a screen reader hears unless aria-valuetext is passed.
`role`	`AriaRole \| undefined`	Not set	—

Accessibility

Reports role="progressbar" with aria-valuenow
role="meter" is accepted for scalar readings inside a known range
The label is tied to the bar
Work not yet counted reports aria-busy and the value text "Loading"; under reduced motion it holds still at half strength

BadgealternativeUse Badge for status without percentage
AlertsiblingUse Alert for completion messages
LoadingalternativeUse Loading when there is no bar to fill

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.