Progress Indicator
Material Design 3 linear and circular progress indicators for
determinate and indeterminate loading states. Not intended as a
generic spinner replacement when no meaningful progress or activity
context is available.
Basic Usage
Use linear or circular progress with a determinate value. Choose
form factor based on available space and content flow.
<ds-linear-progress value="45" label="Upload progress"></ds-linear-progress>
<ds-circular-progress value="45" label="Upload progress"></ds-circular-progress>
Initial Value
Configure max range and custom color for startup states.
<ds-linear-progress value="30" max="80" color="secondary" label="Storage used"></ds-linear-progress>
<ds-circular-progress value="30" max="80" color="secondary" label="Storage used"></ds-circular-progress>
Variants
Combine type, size, and color variants for different surfaces.
Linear Colors
Circular Sizes
<ds-circular-progress size="sm" value="75"></ds-circular-progress>
<ds-circular-progress size="md" value="75"></ds-circular-progress>
<ds-circular-progress size="lg" value="75"></ds-circular-progress>
<ds-circular-progress size="96" value="75"></ds-circular-progress>
States
Use indeterminate mode when exact completion is unknown.
<ds-linear-progress indeterminate></ds-linear-progress>
<ds-circular-progress indeterminate></ds-circular-progress>
Interactive Example
Update progress value and toggle indeterminate mode live.
API
Attributes
| Element |
Attribute |
Type |
Default |
Description |
ds-linear-progress |
value |
number |
0 |
Current progress value. |
ds-linear-progress |
max |
number |
100 |
Maximum progress value. |
ds-linear-progress |
indeterminate |
boolean |
false |
Displays animated indeterminate state. |
ds-linear-progress |
color |
string |
primary |
primary, secondary,
tertiary, error.
|
ds-linear-progress |
label |
string |
none |
Accessible name announced to screen readers. Falls back to
"Loading" (indeterminate) or "N% complete" (determinate)
when unset — always set a real one when the progress bar
has specific context (e.g. "Upload progress").
|
ds-circular-progress |
value |
number |
0 |
Current progress value. |
ds-circular-progress |
max |
number |
100 |
Maximum progress value. |
ds-circular-progress |
indeterminate |
boolean |
false |
Displays animated indeterminate state. |
ds-circular-progress |
size |
string | number |
md |
sm, md, lg, aliases
small/medium/large, or
pixel value.
|
ds-circular-progress |
color |
string |
primary |
primary, secondary,
tertiary, error.
|
ds-circular-progress |
label |
string |
none |
Accessible name announced to screen readers. Same fallback
behavior as ds-linear-progress.
|
Properties
| Property |
Type |
Description |
value |
number |
Get/set current value. |
max |
number |
Get/set maximum value. |
indeterminate |
boolean |
Get/set indeterminate mode. |
color |
string |
Get/set indicator color scheme. |
size (circular) |
string |
Get/set circular indicator size token or pixel value. |
Methods
| Method |
Description |
getProgress() |
Returns current progress percentage clamped to 0-100. |
getSizeValue() (circular) |
Returns computed circular size in pixels. |
Events
| Event |
Detail |
Description |
| None |
N/A |
This component currently does not emit custom events. |
CSS Parts
| Part |
Description |
| None |
This component currently does not expose shadow parts. |
CSS Custom Properties
| Property |
Description |
--ds-linear-progress-track-size |
Linear track height. Default var(--ds-space-1).
|
--ds-linear-progress-radius |
Linear track radius. Default
calc(var(--ds-space-1) / 2).
|
--ds-circular-progress-size-sm |
Small circular size token. Default
var(--ds-size-icon-lg).
|
--ds-circular-progress-size-md |
Medium circular size token. Default
var(--ds-size-control-lg).
|
--ds-circular-progress-size-lg |
Large circular size token. Default
calc(var(--ds-size-control-lg) + var(--ds-space-4)).
|
Accessibility
Keyboard Interaction
| Key |
Context |
Expected Result |
Tab |
Adjacent controls in demo |
Moves focus to interactive inputs controlling progress |
Arrow Left/Right |
Focus on value slider |
Adjusts determinate progress value |
Semantics
-
Uses
role="progressbar" with
aria-valuemin and aria-valuemax.
-
Determinate mode exposes
aria-valuenow; indeterminate
mode omits it per ARIA guidance.
-
Always has an accessible name: the
label
attribute, when set, becomes aria-label. When
unset, it falls back to "Loading" (indeterminate) or
"N% complete" (determinate) so the progressbar is never
nameless — but set label whenever the bar has
real context (e.g. "Upload progress") rather than relying on
the generic fallback.
Usage Guidelines
-
When to use: Use determinate indicators when
measurable progress is available and indeterminate indicators for
unknown-duration work.
-
When not to use: Avoid perpetual loaders without
contextual feedback or completion outcomes.
-
Composition: Prefer linear indicators in flowing
layouts/forms and circular indicators in compact or centered
loading surfaces.
-
Common mistakes: Switching between determinate
and indeterminate states without context can confuse users.