Progress Bar

v1.1.5

Ready for Production

Catalyst Progress Bar 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';

Variants

Vertical

Set orientation="vertical" on ProgressRoot to render a top-to-bottom indicator. Use translateY instead of translateX on the indicator's transform.

Disabled

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

Common Patterns

Animated

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

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.

Segmented — Progress

Pass a fractional value (relative to max) to show partial segment fills alongside fully filled ones.

Long-Running Process

For longer processes, announce the start, key milestones, and completion via an always-rendered role="status" live region — not every value change. Activate Start process to run a 10-second simulation.

API Reference

Progress Bar 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 Bar is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

The Catalyst Progress Bar component is display-only and has no keyboard interactions of its own. Screen readers do not reliably announce value changes automatically — use a role="status" live region to announce key milestones, as shown in Long-Running Process.

ARIA

• Radix UI renders role="progressbar", aria-valuenow, aria-valuemin, and aria-valuemax automatically.

• When disabled is set, ProgressRoot renders aria-disabled="true" so screen readers announce the disabled state.

• For indeterminate states (unknown duration), omit value — Radix sets aria-valuenow to null and data-state="indeterminate". Consider using Spinner instead for indefinite loading.

• Every progressbar must have a programmatically determinable accessible name — the role alone does not convey context, and nearby text is not associated automatically:

  • Visible label present: give the label an id and reference it from ProgressRoot with aria-labelledby.
  • No visible label: provide the name directly on ProgressRoot with aria-label.

  // With a visible label
  const labelId = useId();
  <Label id={labelId}>Course completion</Label>
  <ProgressRoot aria-labelledby={labelId} value={50}>
    <ProgressIndicator />
  </ProgressRoot>
  
  // Without a visible label
  <ProgressRoot aria-label="Upload progress" value={30}>
    <ProgressIndicator />
  </ProgressRoot>

  See the WAI-ARIA APG naming guidance for details.

• 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 — Level AAA).

See the Radix Progress accessibility docs for inherited baseline behavior.

Choosing the Right Component

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

Related

• Spinner
• Skeleton
• Toast