Progress

A headless, accessible progressbar with ARIA state and a CSS-variable-driven indicator.

Features

Accessible progress semantics
Human-readable value text
CSS variable driven indicator
Stateful data attributes
Fully composable

Installation

npm install @ariaui/progress

Examples

Determinate or indeterminate progress with ARIA values. Drive the indicator width with CSS variables from the component.

Uncontrolled

A static progressbar with no extra React state in the example.

Preview

No preview output yet.

live.tsxReady

Controlled

A controlled progressbar driven by React state and explicit controls.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as Progress from "@ariaui/progress";

export default function Example() {
  return (
    <Progress.Root>
      <Progress.Indicator />
    </Progress.Root>
  );
}

API Reference

Root

Progressbar container. Exposes ARIA state for assistive tech and publishes the normalized percentage as the `--progress-value` CSS variable for the Indicator.

Prop	Type	Default
value	number	—
defaultValue	number	0
onValueChange	(value: number) => void	—
min	number	0
max	number	100
valueText	string	—

Attribute	Values
role	'progressbar'
aria-valuenow	current value
aria-valuemin	min
aria-valuemax	max
aria-valuetext	valueText when provided
data-value	current value
data-min	min
data-max	max

Indicator

Visual fill that reflects progress. Its `width` is driven by the `--progress-value` CSS variable set on Root, so you style size with tokens while the percentage updates automatically.

Accessibility

Progress follows the WAI-ARIA Meter/Progressbar pattern:

Root renders with role="progressbar" and publishes aria-valuenow, aria-valuemin, and aria-valuemax from the value, min, and max props.
Provide valueText when the raw number isn't meaningful on its own — for example "Step 3 of 5" or "45 seconds remaining". This maps to aria-valuetext.
Pair the progressbar with a visible label and associate it via aria-labelledby (or use aria-label when the label lives outside the document flow).
Indeterminate progress is not yet built in — omit aria-valuenow yourself and style the Indicator with your own animation when the value is unknown.
The component is non-interactive and does not receive focus, matching the ARIA specification.