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
| Prop | Type | Default | Description |
|---|---|---|---|
| progress | number | Required | Progress from 0 to 1; values are safely clamped |
| color | Color | "highlight" | Semantic fill color |
| size | "small" | "medium" | "medium" | Track height: 4px or 8px |
| aria-label | string | "Progress" | Accessible name when no visible label exists |
| aria-labelledby | string | - | ID of a visible label |
| jss | JSS | - | Custom styles for the track |
Basic usage
<ProgressBar progress={0.66} aria-label="Upload progress" />
Sizes
small
medium
<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
0%
25%
50%
75%
100%
<ProgressBar progress={0} /> // Empty
<ProgressBar progress={0.5} /> // Half
<ProgressBar progress={1} /> // Complete
With percentage label
Uploading assets72%
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