Skip to content

Progress Bar

Shows how far a task has got, or that it is working when the duration is unknown.

betaReact AriaSource
Uploading receipts64%

Installation

pnpm add @syntara/react @syntara/tokens
import { ProgressBar } from '@syntara/react';

Usage

import { ProgressBar } from '@syntara/react';

export function Upload({ percent }: { percent: number }) {
  return <ProgressBar label="Uploading receipts" value={percent} showValue />;
}

Examples

Indeterminate

A sliding segment when the duration is unknown; a quiet static bar with reduced motion.

Preparing your export

Tones, ranges and sizes

Success, warning and danger fills, a custom range with a value label, and the small size.

Annual limit used38%
Profile complete100%
Storage4.1 of 5 GB
Outpatient limit96%

Accessibility

No keyboard interaction of its own.

  • role="progressbar" with aria-valuenow/min/max and aria-valuetext from React Aria; indeterminate bars omit aria-valuenow.
  • The label is wired with aria-labelledby.
  • Tone changes the fill colour only; say what it means in the label or nearby text.
  • The indeterminate slide runs only under prefers-reduced-motion: no-preference and follows the reading direction.

Guidelines

Do

  • Use determinate progress whenever you can compute it.
  • Use warning/danger for limits (storage, spend), not for task progress.

Don’t

  • Don't use a progress bar for a value that isn't progress toward something — use a meter or text.
  • Don't show an indeterminate bar for less than a second; show nothing, or a Spinner.

API reference

ProgressBar

label
ReactNode

Visible label. Without one, pass aria-label or aria-labelledby (the types require one of the three).

value
number

Current value, between minValue and maxValue.

Default 0

minValue
number

Lowest value.

Default 0

maxValue
number

Highest value.

Default 100

isIndeterminate
boolean

Unknown duration: no value is announced and a segment slides along the track.

Default false

showValue
boolean

Shows the formatted value at the inline end of the label row.

Default false

formatOptions
Intl.NumberFormatOptions

How the value is formatted.

Default { style: 'percent' }

valueLabel
ReactNode

Replaces the formatted value, e.g. '4.1 of 5 GB'.

tone
  • defaultdefault
  • success
  • warning
  • danger

Fill colour. default uses the brand accent.

size
  • sm
  • mddefault

Track thickness: 4px or 8px.

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour7
accent.bgfeedback.danger.solidfeedback.success.solidfeedback.warning.solidsurface.sunkentext.defaulttext.subtle
Type5
font.bodyfont.size.smfont.weight.mediumline-height.snugfont.tracking.sm
Space and size3
space.1space.2space.3
Shape1
radius.pill
Depth2
shadow.highlighthairline
Motion2
motion.duration.slowmotion.easing-out