ProgressBar

A quiet linear indicator for showing the completion of an ongoing process. Its tonal track sits within the surrounding surface while the fill carries emphasis.

Props

Basic usage

<ProgressBar progress={0.66} aria-label="Upload progress" />

Sizes

<ProgressBar progress={0.5} size="small" />   // 4px
<ProgressBar progress={0.5} size="medium" />  // 8px, default

Colors

<ProgressBar color="highlight" progress={0.66} />  // Accent color
<ProgressBar color="negative" progress={0.66} />   // Error/danger
<ProgressBar color="warning" progress={0.66} />    // Warning

Progress states

<ProgressBar progress={0} />                  // Empty
<ProgressBar progress={0.5} />                // Half
<ProgressBar progress={1} />   // Complete

With percentage label

function UploadProgress({ progress }) {
  const percentage = Math.round(progress * 100);

  return (
    <Column gap="small">
      <Row justify="space-between">
        <Span id="upload-progress-label">Uploading assets</Span>
        <Span color="secondary">{percentage}%</Span>
      </Row>
      <ProgressBar
        progress={progress}
        aria-labelledby="upload-progress-label"
      />
    </Column>
  );
}

Dynamic color based on value

function StorageIndicator({ used, total }) {
  const progress = used / total;

  // Change color based on usage
  const color =
    progress > 0.9 ? "negative" : progress > 0.7 ? "warning" : "highlight";

  return (
    <Column gap="small">
      <Row justify="space-between">
        <Span>Storage</Span>
        <Span color="secondary">{Math.round(progress * 100)}% used</Span>
      </Row>
      <ProgressBar color={color} progress={progress} size="small" />
    </Column>
  );
}

Behavior

• Values are clamped between 0 and 1, including values received during asynchronous updates.
• Changes animate smoothly without changing layout.
• Motion is removed when the user prefers reduced motion.
• Progress fills from the leading edge, including in right-to-left layouts.
• Keep progress moving forward. A bar that rewinds can make the process feel unreliable.

ProgressBar renders the progressbar role and percentage-based ARIA values. Connect a visible description with aria-labelledby; use aria-label when there is no visible label.

Use cases

• File uploads: Show upload completion
• Storage usage: Display disk/quota usage
• Form completion: Indicate steps completed
• Loading states: Show determinate loading progress