XDS — Design System

ProgressBar@xds/core · XDSProgressBar v0.0.13

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.

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

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.

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" />;
}

Usage

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

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.

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> ); }

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> ); }

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> ); }

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> ); }