Progress
Something is working - and the user should never have to guess. Use a progress indicator whenever a wait lasts long enough to notice (roughly a second or more).
| Shape | Feels like | Best for |
|---|---|---|
| Circular | A pulse next to the action | Buttons, table cells, compact panels |
| Linear | A bar across the surface | Page loads, uploads, full-width cards |
Both shapes share two modes:
| Mode | When |
|---|---|
| Indeterminate (default) | You know it's busy, but not how far - API calls, auth checks |
| Determinate | You can measure it - pass value from 0 to 100 |
In context
A short status line plus a spinner keeps the wait grounded in what the user asked for.
Circular
Compact by design. Default size is 40px - drop it next to a label, inside a button, or in a dense table cell.
Waiting (indeterminate)
Measuring (determinate)
Pass value when you can report how far along you are.
Colors
GDS styles primary and inherit. Use inherit when the spinner sits on a
colored surface and should match nearby text.
Percent in the ring
Layer a label over the circle when the number itself matters.
Linear
A thin bar that stretches with its container. Give it a width (or a sized parent) so it has room to breathe.
Waiting (indeterminate)
Measuring (determinate)
Buffer
Two values at once - how far playback (or download) has gone (value), and how
far content is already buffered (valueBuffer). Classic for streaming.
Colors
Accessibility
Progress is visual by default. Always say what is happening.
<GdsCircularProgress aria-label="Loading users" />Props
External references
For complete CircularProgress and LinearProgress props, use the MUI references below.