ProgressRing supplies a circular appearance for Progress. It shares the root’s custom range, null, formatting, labeling, native prop, ref, and render contract. Optional children display a preformatted value beside the ring.
Usage
Supply the raw controlled value and an accessible name. Usearia-valuetext when a formatted value explains progress more clearly than a percentage.
aria-labelledby to associate the ring with an existing visible label, or compose Progress.Label as a child. Preformatted children do not automatically provide the ring’s accessible name.
Controlled progress and ranges
The application calculatesvalue and formats display content. The ring does not fetch data, advance progress, or calculate quotas. min defaults to 0, and max defaults to 100. Finite values are clamped to the range for semantic values and arc geometry. The arc fills by the normalized percentage, including when the minimum is nonzero.
Pass value={null} for indeterminate progress. The ring omits aria-valuenow and displays an indeterminate arc. Non-finite values also remain indeterminate; they do not become zero or completion. Display content stays controlled by the application.
Use locale, format, and getAriaValueText as described in Progress. Compose Progress.Value to display the root’s formatted value.
Use ProgressBar for horizontal progress or MetricRow for a label and aligned value.
Appearance and composition
size="md" renders a 16px ring; size="sm" renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. barColor accepts CSS colors, including theme variables. The SVG is decorative and hidden from accessibility APIs.
Value changes animate for 300ms. Reduced-motion preferences disable the transition and indeterminate rotation. Native attributes, className, style, and ref target the outer progress element. className and style can receive the progress state. render can replace the root while retaining its semantics.
Props
string
Accessible name identifying the measured operation.
string
ID of the visible label that names the operation.
string
Human-readable progress value overriding the default formatted value.
string
CSS color of the filled arc. Defaults to the blue theme color.
ReactNode
Optional preformatted value or Progress parts displayed before the ring.
string | ((state: ProgressRootState) => string | undefined)
Class applied to the progress root, or a callback receiving its status.
NumberFormatOptions
Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
((formattedValue: string, value: number | null) => string)
Receives the formatted value and raw value, including null, and returns an accessible value description.
LocalesArgument
Locale or locale list used to format the value. Defaults to the runtime locale.
number
default:"100"
Inclusive maximum. Defaults to 100.
number
default:"0"
Inclusive minimum. Defaults to 0.
Ref<HTMLDivElement>
Ref to the root div, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>
Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
"md" | "sm"
default:"md"
Ring diameter: sm (14px) or md (16px). Defaults to md.
CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)
Inline styles applied to the progress root, or a callback receiving its status.
number | null
required
Controlled value in the min/max range. Use null for indeterminate progress.