Progress

v1.1.3

Documentation Under Review

Catalyst Progress extends Radix UI Progress with built-in design tokens, CVA variants, and accessibility defaults — giving you a production-ready progress bar, segmented step indicator, or animated loader with zero configuration.

Installation

npm install @pmi/catalyst-progress

import { ProgressRoot, ProgressIndicator } from '@pmi/catalyst-progress';

Common Patterns

Animated

Animate the indicator when the value changes by adding a CSS transition to the transform style.

Disabled

Set disabled on ProgressRoot to apply reduced opacity and block interaction.

With Label — Steps

Pair the progress bar with a step counter label for multi-step workflows.

With Label — Percentage

Display a percentage value alongside the progress bar.

Segmented — Steps

Use hasSegments with max equal to the total number of steps. Each segment fills individually with a staggered animation.

API Reference

Progress is a compound component built on Radix UI Progress. The sections below summarize the props for each part.

ProgressRoot

The container that sets orientation, size, disabled state, and optionally renders segmented slot dividers.

Accepts all standard Radix Progress Root props and forwards ref.

ProgressIndicator

The visual fill element. Use style={{ transform }} to drive the position from value, and the hasPartialAnimation / showPartial / partialSize props for fractional segment fills.

Accepts all standard Radix Progress Indicator props and forwards ref.

Accessibility

Progress is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

The Progress component is display-only and has no keyboard interactions of its own. Screen readers announce progress updates automatically when value changes.

ARIA

• Radix UI renders role="progressbar", aria-valuenow, aria-valuemin, and aria-valuemax automatically.
• For indeterminate states (unknown duration), omit value — Radix sets aria-valuenow to null and data-state="indeterminate". Consider using Spinner instead for indefinite loading.
• Always provide surrounding text or a <label> that describes what the progress bar represents — the progressbar role alone does not convey context.
• When using custom colours, verify the indicator-to-track contrast ratio meets the WCAG 2.2 AA non-text contrast minimum of 3:1 (SC 1.4.11).
• For animated indicators, consider respecting prefers-reduced-motion to avoid discomfort for motion-sensitive users (WCAG 2.2 SC 2.3.3 — AAA, but recommended at AA).

See the Radix Progress accessibility docs for inherited baseline behavior.

Choosing the Right Component

Use Progress when the completion percentage or step count is known in advance. Reach for a different primitive when:

Related

• Spinner
• Skeleton
• Toast