Progress Ring
Progress rings provide users with visual feedback about the status of ongoing processes through a circular progress indicator. This component displays both determinate progress with specific percentages and indeterminate loading states.
import {ProgressRing} from "@qualcomm-ui/react/progress-ring"Overview
The progress ring can be in one of two states:
- indeterminate: the default state.
- determinate: assumed when the value prop is passed.
Indeterminate progress rings keep users informed that work is happening when timeframes are unknown.
Examples
Simple
For most use cases, you can use the simple ProgressRing component.
<ProgressRing />
Composite
Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.
import type {ReactElement} from "react"
import {ProgressRing} from "@qualcomm-ui/react/progress-ring"
export function ProgressRingCompositeDemo(): ReactElement {
return (
<ProgressRing.Root size="lg">
<ProgressRing.CircleContainer>
<ProgressRing.Circle>
<ProgressRing.Track />
<ProgressRing.Bar />
</ProgressRing.Circle>
</ProgressRing.CircleContainer>
<ProgressRing.Label>Loading...</ProgressRing.Label>
</ProgressRing.Root>
)
}Value
When the value prop is set, the filled portion of the circle will represent the total percent relative to max and min. This is referred to as the "determinate" state.
0%
<ProgressRing
size="lg"
value={value}
valueText={(api) => `${api.valuePercent}%`}
/>
Value Text
Display the value text by passing a value to the valueText prop. The value text only shows when the size is lg or xl.
0%
<ProgressRing
size="lg"
value={value}
valueText={(api) => `${api.valuePercent}%`}
/>
Sizes
Use the size prop to change the size of the circle.
xxs
xs
sm
md
lg
0%
xl
0%
import {type ReactElement, useEffect, useState} from "react"
import {ProgressRing} from "@qualcomm-ui/react/progress-ring"
export function ProgressRingSizesDemo(): ReactElement {
const [value, setValue] = useState<number>(0)
useEffect(() => {
function increment() {
setValue((prevValue) => {
if (prevValue === 100) {
return 0
}
return prevValue + 10
})
}
const timer = setInterval(increment, 1000)
return () => clearInterval(timer)
}, [])
return (
<div className="flex items-center gap-4">
<div className="grid grid-cols-3 items-center justify-items-center gap-x-8 gap-y-4">
<div className="font-heading-xs text-neutral-primary">xxs</div>
<ProgressRing size="xxs" value={value} />
<ProgressRing size="xxs" />
<div className="font-heading-xs text-neutral-primary">xs</div>
<ProgressRing size="xs" value={value} />
<ProgressRing size="xs" />
<div className="font-heading-xs text-neutral-primary">sm</div>
<ProgressRing size="sm" value={value} />
<ProgressRing size="sm" />
<div className="font-heading-xs text-neutral-primary">md</div>
<ProgressRing size="md" value={value} />
<ProgressRing size="md" />
<div className="font-heading-xs text-neutral-primary">lg</div>
<ProgressRing
size="lg"
value={value}
valueText={(api) => `${api.valuePercent}%`}
/>
<ProgressRing size="lg" />
<div className="font-heading-xs text-neutral-primary">xl</div>
<ProgressRing
size="xl"
value={value}
valueText={(api) => `${api.valuePercent}%`}
/>
<ProgressRing size="xl" />
</div>
</div>
)
}Thickness
Use the thickness prop to change the pixel width of the track and bar.
<ProgressRing className="py-2" size="lg" thickness={8} />
Disabled
Use the disabled prop to indicate that the progress indicator is inactive.
64%
<ProgressRing disabled label="Indeterminate" size="lg" />
<ProgressRing
disabled
label="Determinate"
size="lg"
value={64}
valueText="64%"
/>
Shortcuts
The ProgressRing.Circle component automatically renders the track and bar components when child. The following two examples are
<ProgressRing.Circle />Accessibility
- When the value is supplied, the component automatically provides the corresponding
aria-value*attributes to the element. - The progress element is automatically marked with
role="progressbar". - The label is automatically associated with the progress bar. If you omit the label property, the
aria-labelof the progress element defaults to the value when determinate, and "Loading" when indeterminate.
Explorer
64%
Component Anatomy
Hover to highlight, click to view API
API
<ProgressRing>
The ProgressRing component extends the ProgressRing.Root with the following props:
A circular progress indicator that displays progress as a ring with optional
value text and labels.
Description
Props passed to the progress bar.
Description
Props passed to the progress circle container.
Description
Props passed to the progress circle.
Description
Props passed to the error text.
Description
Props passed to the progress label.
Description
Props passed to the progress track.
Description
Value text Render Prop
Description
Props passed to the value text.
ProgressApi
This API is accessible in JSX via the <ProgressRing.Context> component:
<ProgressRing.Context>
{(api: ProgressApi) => {
return <>{/*...*/}</>
}}
</ProgressRing.Context>Type
booleanDescription
Whether the progress bar is indeterminate
Type
numberDescription
The maximum value of the progress bar.
Type
numberDescription
The minimum value of the progress bar.
Type
(
value: number,
) => void
Description
Sets the value of the progress bar.
Type
| 'indeterminate'
| 'complete'
| 'loading'
Description
The computed state of the progress bar, based on the
value.Type
numberDescription
The current value of the progress bar.
Type
numberDescription
The current value of the progress bar as a percentage, computed from the
min
and max values.Composite API
<ProgressRing.Root>
The root container element for the progress ring component. Renders a
<div>
element by default.Type
numberDescription
The initial value of the progress when it is first rendered. Use when you do
not need to control the state of the progress.
Type
'ltr' | 'rtl'
Description
The document's text/writing direction.
Type
booleanDescription
If
true, the progress is disabled.Type
| 'primary'
| 'neutral'
Description
Governs the color of the progress circle.
Type
Partial<{
errorText: string
hint: string
label: string
progress: string
}>
Description
The element ids that are associated with the progress. These will be
automatically generated if omitted.
Type
booleanDescription
If
true, the progress is marked as invalid.Type
numberDescription
Maximum value.
Type
numberDescription
Minimum value.
Type
(
value: number | undefined,
) => void
Description
Callback fired when the value changes.
Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
Type
| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number
Description
Governs the height of the progress circle and track.
Type
| string
| number
Description
The thickness of the progress ring in pixels. If supplied as a number, it
will be used as the pixel value.
The default value varies based on the size of the progress circle.
The default value varies based on the size of the progress circle.
Type
numberDescription
The value of the progress. If omitted, the component will render as an
indefinite progress bar.
classNameValue
'qui-progress-ring__root'data-disabledValue
data-invalidValue
data-maxValue
numberdata-progress-partValue
'root'data-sizeValue
| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number
data-stateValue
| 'indeterminate'
| 'complete'
| 'loading'
data-valueValue
numberstyleValue
<ProgressRing.Label>
Label text associated with the progress ring. Renders a
<label> element by
default.Type
stringDescription
id attribute. If
omitted, a unique identifier will be automatically generated for accessibility.
Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
classNameValue
'qui-progress-ring__label'data-progress-partValue
'label'<ProgressRing.ValueText>
Displays the current progress value as text. Only visible when size is
lg or
xl. Renders a <div> element by default.Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
classNameValue
'qui-progress-ring__value-text'data-invalidValue
data-progress-partValue
'value-text'hiddenValue
boolean<ProgressRing.ErrorText>
Error message displayed when the progress ring is in an invalid state. Renders a
<div> element by default.Type
stringDescription
id attribute. If
omitted, a unique identifier will be automatically generated for accessibility.
Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
classNameValue
'qui-progress-ring__error-text'data-progress-partValue
'error-text'hiddenValue
boolean<ProgressRing.CircleContainer>
Container element that wraps the circle and value text. Renders a
<div> element
by default.Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
classNameValue
'qui-progress-ring__circle-container'data-progress-partValue
'circle-container'<ProgressRing.Circle>
The SVG element that contains the track and bar. Renders an
<svg> element.Type
stringDescription
id attribute. If
omitted, a unique identifier will be automatically generated for accessibility.
classNameValue
'qui-progress-ring__circle'data-disabledValue
data-emphasisValue
| 'primary'
| 'neutral'
data-progress-partValue
'circle'data-sizeValue
| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number
data-stateValue
| 'indeterminate'
| 'complete'
| 'loading'
styleValue
<ProgressRing.Track>
The background track of the progress ring. Renders a
<circle> element.classNameValue
'qui-progress-ring__track'data-disabledValue
data-progress-partValue
'circle-track'data-sizeValue
| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number
data-stateValue
| 'indeterminate'
| 'complete'
| 'loading'
<ProgressRing.Bar>
The filled portion of the progress ring that represents the current progress
value. Renders a
<circle> element.classNameValue
'qui-progress-ring__bar'data-disabledValue
data-emphasisValue
| 'primary'
| 'neutral'
data-invalidValue
data-maxValue
numberdata-progress-partValue
'circle-bar'data-sizeValue
| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number
data-stateValue
| 'indeterminate'
| 'complete'
| 'loading'
styleValue
Last updated on by Ryan Bower