Progress indicators
Material standard and expressive linear/circular progress indicators with React Aria progress semantics and explicit web adaptations.
Progress indicators communicate the status of an ongoing process. Use determinate progress when completion can be measured and indeterminate progress when it cannot.
Material 3 progress indicators
import {
CircularProgressIndicator,
LinearProgressIndicator,
} from '@m3-ui/ui';
<LinearProgressIndicator aria-label="Upload progress" value={0.64} />
<CircularProgressIndicator aria-label="Loading" isIndeterminate />Families
The public baseline family contains LinearProgressIndicator and CircularProgressIndicator. LinearWavyProgressIndicator and CircularWavyProgressIndicator expose the audited M3 Expressive waveform family.
Choose the family that matches the product's Material language; do not use decorative progress motion when no process is actually being communicated.
Determinate and indeterminate
Pass value for known progress or isIndeterminate when completion cannot be estimated. The component delegates progress range/value semantics to React Aria while Material owns the visual track/indicator geometry and motion.
The rendered visual drawing is hidden from accessibility so SVG/path implementation details are not announced as duplicate content.
Expressive waveform
Wavy indicators preserve the audited waveform/amplitude/motion behavior. Renderer controls such as amplitude/wavelength/speed are implementation controls, not a new set of normative Material design tokens.
Reduced-motion preference removes or freezes motion while preserving a valid progress visual and unchanged progressbar semantics.
Web compatibility adaptations
bufferValue on standard linear progress and fourColor on standard indeterminate indicators are audited Material Web compatibility surfaces. They remain explicitly classified as adaptations rather than generalized to every Material/Compose progress family.
Accessibility
Every standalone indicator needs an accessible label via aria-label or aria-labelledby because the Material visual does not render a visible label. For determinate progress, let React Aria expose the current numeric value/range rather than duplicating it in the SVG.
Do not move focus to a progress indicator merely because progress changes. Use surrounding status messaging when a process needs additional announcement.
API reference
LinearProgressIndicator
LinearProgressIndicator(props: LinearProgressIndicatorProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
bufferValue | number | undefined | — | Web public adaptation: known buffered progress, in the same range as value. | @m3-ui/ui |
color | Property.Color | undefined | — | — | @m3-ui/ui |
fourColor | boolean | undefined | — | Web public adaptation for indeterminate mode. | @m3-ui/ui |
style | StyleOrFunction<ProgressBarRenderProps> | undefined | — | — | @m3-ui/ui |
trackColor | Property.Color | undefined | — | — | @m3-ui/ui |
Inherited React / web props (83)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
className | ClassNameOrFunction<ProgressBarRenderProps> | undefined | 'react-aria-ProgressBar' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
dir | string | undefined | — | — | @react-types/shared |
formatOptions | Intl.NumberFormatOptions | undefined | { style: 'percent' } | The display format of the value label. | react-aria |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isIndeterminate | boolean | undefined | — | Whether presentation is indeterminate when progress isn't known. | react-aria |
lang | string | undefined | — | — | @react-types/shared |
maxValue | number | undefined | 100 | The largest value allowed for the input. | react-aria |
minValue | number | undefined | 0 | The smallest value allowed for the input. | react-aria |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
render | DOMRenderFunction<"div", ProgressBarRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
value | number | undefined | 0 | The current value (controlled). | react-aria |
valueLabel | ReactNode | — | The content to display as the value's label (e.g. 1 of 4). | react-aria |
Source: packages/ui/src/components/ProgressIndicator/ProgressIndicator.tsx:659
Material fidelity and web adaptation
- Family
- Progress indicators
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- LinearProgressIndicator · CircularProgressIndicator · LinearWavyProgressIndicator · CircularWavyProgressIndicator
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements standard linear/circular progress plus M3 Expressive wavy linear/circular variants, determinate and indeterminate states, canonical stop/track geometry, reduced-motion behavior, and the current Compose-derived wavy amplitude and wavelength lifecycle.
- Behavior fidelity
- adapted: React Aria ProgressBar owns progressbar semantics and value ranges; indicators require an accessible name because the visual has no label. Standard `bufferValue` and indeterminate `fourColor` remain audited Material Web renderer adaptations and are intentionally not inherited by the wavy Compose-aligned APIs.
- Semantics fidelity
- adapted: React Aria ProgressBar owns progressbar semantics and value ranges; indicators require an accessible name because the visual has no label. Standard `bufferValue` and indeterminate `fourColor` remain audited Material Web renderer adaptations and are intentionally not inherited by the wavy Compose-aligned APIs.
- Adaptations
- React Aria ProgressBar owns progressbar semantics and value ranges; indicators require an accessible name because the visual has no label. Standard `bufferValue` and indeterminate `fourColor` remain audited Material Web renderer adaptations and are intentionally not inherited by the wavy Compose-aligned APIs.
Material supplies progress visual hierarchy, geometry, color, waveform, and motion. React Aria ProgressBar owns accessible progress semantics; buffer/four-color support remains explicitly audited Material Web adaptation.
Related components
- Loading indicator — expressive morphing loading affordance.
- Snackbar — transient status messaging.