Loading indicator
M3 Expressive morphing loading indicators with contained/uncontained forms, determinate progress, and accessible progress semantics.
Loading indicators use the Material 3 expressive morphing shape sequence to communicate loading or progress. Use the standard progress-indicator family when the product calls for conventional linear/circular progress instead.
import { ContainedLoadingIndicator, LoadingIndicator } from '@m3-ui/ui';
<LoadingIndicator aria-label="Loading" />
<ContainedLoadingIndicator aria-label="Preparing workspace" />
<LoadingIndicator aria-label="Import progress" value={0.72} />When to use
Use the expressive loading indicator where the Material expressive loading affordance is appropriate. Do not use it as decorative looping animation unrelated to a process.
LoadingIndicator is uncontained; ContainedLoadingIndicator uses its audited Material container and indicator color roles rather than a docs-only wrapper.
Indeterminate and determinate modes
Omit value for indeterminate loading. Provide a value for determinate progress. The public implementation safely maps determinate progress into the supported Material range while React Aria remains the semantic progress owner.
Shape and motion
The renderer follows the audited Material/Compose shape sequence and motion timing. Internal Material Shapes code exists to draw the component and is not exposed as a general-purpose public shape API.
With prefers-reduced-motion: reduce, the visual freezes at a valid frame while the accessible progress state remains unchanged.
Accessibility
React Aria ProgressBar owns the semantic progress contract. The SVG drawing is hidden from accessibility, so every standalone indicator needs aria-label or aria-labelledby.
Do not add a duplicate live region that announces every animation frame. If the application needs status text such as “Preparing workspace,” expose stable meaningful status separately.
API reference
LoadingIndicator
LoadingIndicator({ color, ...props }: LoadingIndicatorProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
color | Property.Color | undefined | — | — | @m3-ui/ui |
style | StyleOrFunction<ProgressBarRenderProps> | undefined | — | — | @m3-ui/ui |
value | number | undefined | — | Provide a value from 0..1 for determinate mode; omit it for indeterminate mode. | @m3-ui/ui |
Inherited React / web props (79)
| 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 |
lang | string | undefined | — | — | @react-types/shared |
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 |
valueLabel | ReactNode | — | The content to display as the value's label (e.g. 1 of 4). | react-aria |
Source: packages/ui/src/components/LoadingIndicator/LoadingIndicator.tsx:212
Material fidelity and web adaptation
- Family
- Loading indicator
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- LoadingIndicator · ContainedLoadingIndicator
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements the expressive morphing loading indicator and contained variant with the canonical Material shape sequence, Compose-derived motion timing, 0..1 determinate morphing, indeterminate shape cycling, and reduced-motion freezing.
- Behavior fidelity
- adapted: React Aria ProgressBar owns progress semantics. Omitting `value` selects indeterminate mode and supplying a value selects determinate mode; the SVG renderer is aria-hidden and consumers must provide an accessible name. The Material Shapes port remains an internal renderer mechanism rather than a new public shape contract.
- Semantics fidelity
- adapted: React Aria ProgressBar owns progress semantics. Omitting `value` selects indeterminate mode and supplying a value selects determinate mode; the SVG renderer is aria-hidden and consumers must provide an accessible name. The Material Shapes port remains an internal renderer mechanism rather than a new public shape contract.
- Adaptations
- React Aria ProgressBar owns progress semantics. Omitting `value` selects indeterminate mode and supplying a value selects determinate mode; the SVG renderer is aria-hidden and consumers must provide an accessible name. The Material Shapes port remains an internal renderer mechanism rather than a new public shape contract.
Material supplies the expressive shapes, contained/uncontained presentation, colors, and motion. React Aria supplies browser progress semantics, and reduced-motion handling changes animation only—not the process state.
Related components
- Progress indicators — standard and expressive linear/circular progress families.
- Snackbar — transient process/result messaging.