XDS — Design System

XDSProgressBar@xds/core · ProgressBar

Preview coming soon

Usage

A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.

Best practices

Guidance	Practices
Do	Use a determinate bar when the total amount of work is known, and indeterminate when it's not.
Do	Choose a color variant that matches the context — accent for general progress, positive for success, warning or negative for alerts.
Do	Always provide a label, even if hidden — screen readers need it to announce what's loading.
Don't	Place icons or labels inside the bar — compose them alongside it using layout components.
Don't	Use a progress bar for instant actions — it's meant for operations that take noticeable time.
Don't	Use multiple progress bars stacked together for the same operation — use one bar with a value label instead.

Import

ts
import {XDSProgressBar} from '@xds/core/ProgressBar'

Props

Prop	Type	Description
labelrequired	string	Accessible label (required).
value	number (default: 0)	Current value (ignored when indeterminate).
max	number (default: 100)	Maximum value.
isLabelHidden	boolean (default: false)	Visually hide the label (remains accessible).
hasValueLabel	boolean (default: false)	Show formatted value text (ignored when indeterminate).
formatValueLabel	(value: number, max: number) => string	Custom value label formatter; defaults to a percentage string.
variant	'accent' \| 'positive' \| 'warning' \| 'negative' (default: 'accent')	Semantic color variant.
isIndeterminate	boolean (default: false)	Animated loading indicator for unknown progress.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.

ProgressBar — Custom FormatProgress bar with a custom value label showing disk usage in GB.

tsx
'use client';
import {XDSProgressBar} from '@xds/core/ProgressBar';
import {XDSCenter} from '@xds/core/Center';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function ProgressBarCustomFormat() {
  return (
    <XDSCenter width={300}>
      <XDSVStack gap={1}>
        <XDSProgressBar
          value={3.2}
          max={5}
          label="Disk usage"
          hasValueLabel
          formatValueLabel={(value: number, max: number) =>
            `${value} GB / ${max} GB`
          }
        />
        <XDSText type="supporting" color="secondary">
          1.8 GB remaining
        </XDSText>
      </XDSVStack>
    </XDSCenter>
  );
}

ProgressBar — IndeterminateIndeterminate progress bar for operations with unknown duration.

tsx
'use client';
import {XDSProgressBar} from '@xds/core/ProgressBar';
import {XDSCenter} from '@xds/core/Center';
export default function ProgressBarIndeterminate() {
  return (
    <XDSCenter width={300}>
      <XDSProgressBar isIndeterminate label="Loading..." />
    </XDSCenter>
  );
}

ProgressBar — Semantic VariantsAll semantic color variants stacked vertically.

tsx
'use client';
import {XDSProgressBar} from '@xds/core/ProgressBar';
import {XDSCenter} from '@xds/core/Center';
import {XDSVStack} from '@xds/core/Layout';
export default function ProgressBarSemanticVariants() {
  return (
    <XDSCenter width={300}>
      <XDSVStack gap={4}>
        <XDSProgressBar value={60} label="Accent" variant="accent" hasValueLabel />
        <XDSProgressBar value={80} label="Positive" variant="positive" hasValueLabel />
        <XDSProgressBar value={50} label="Warning" variant="warning" hasValueLabel />
        <XDSProgressBar value={92} label="Negative" variant="negative" hasValueLabel />
        <XDSProgressBar value={35} label="Neutral" variant="neutral" hasValueLabel />
      </XDSVStack>
    </XDSCenter>
  );
}

ProgressBar — With Value LabelProgress bar with its current percentage displayed.

tsx
'use client';
import {XDSProgressBar} from '@xds/core/ProgressBar';
import {XDSCenter} from '@xds/core/Center';
export default function ProgressBarWithValueLabel() {
  return (
    <XDSCenter width={300}>
      <XDSProgressBar value={75} label="Storage used" hasValueLabel />
    </XDSCenter>
  );
}

Showcase source

tsx
'use client';
import {XDSProgressBar} from '@xds/core/ProgressBar';
export default function ProgressBarShowcase() {
  return <XDSProgressBar value={60} label="Progress" />;
}