Progress Ring

A small visual indicator that communicates ongoing task execution.

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.

Brand

<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.

Brand

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.

Brand

<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.

Brand

<ProgressRing
  size="lg"
  value={value}
  valueText={(api) => `${api.valuePercent}%`}
/>

Sizes

Use the size prop to change the size of the circle.

Brand

xxs

Thickness

Use the thickness prop to change the pixel width of the track and bar.

Brand

<ProgressRing className="py-2" size="lg" thickness={8} />

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-label of the progress element defaults to the value when determinate, and "Loading" when indeterminate.

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.

Prop	Type
barProps Props passed to the progress bar.	ProgressRingBarProps
circleContainerProps Props passed to the progress circle container.	ProgressRingCircleContainerProps
circleProps Props passed to the progress circle.	ProgressRingCircleProps
errorText Error text rendered below the progress ring when invalid is true.	ReactNode
errorTextProps Props passed to the error text.	ProgressRingErrorTextProps
label Accessible label for the progress ring, rendered below the circle.	ReactNode
labelProps Props passed to the progress label.	ProgressRingLabelProps
trackProps Props passed to the progress track.	ProgressRingTrackProps
valueText Value text Render Prop	BindingRenderProp< ProgressApi, ReactNode >
valueTextProps Props passed to the value text.	ProgressRingValueTextProps

barProps

Type

ProgressRingBarProps

Description

Props passed to the progress bar.

circleContainerProps

Type

ProgressRingCircleContainerProps

Description

Props passed to the progress circle container.

circleProps

Type

ProgressRingCircleProps

Description

Props passed to the progress circle.

errorText

Type

ReactNode

Description

Error text rendered below the progress ring when invalid is true.

errorTextProps

Type

ProgressRingErrorTextProps

Description

Props passed to the error text.

label

Type

ReactNode

Description

Accessible label for the progress ring, rendered below the circle.

labelProps

Type

ProgressRingLabelProps

Description

Props passed to the progress label.

trackProps

Type

ProgressRingTrackProps

Description

Props passed to the progress track.

valueText

Type

BindingRenderProp<
  ProgressApi,
  ReactNode
>

Description

Value text Render Prop

valueTextProps

Type

ProgressRingValueTextProps

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>

Prop	Type
isIndeterminate Whether the progress bar is indeterminate	boolean
max The maximum value of the progress bar.	number
min The minimum value of the progress bar.	number
setValue Sets the value of the progress bar.	( value: number, ) => void
state The computed state of the progress bar, based on the `value`.	\| 'indeterminate' \| 'complete' \| 'loading'
value The current value of the progress bar.	number
valuePercent The current value of the progress bar as a percentage, computed from the `min` and `max` values.	number

isIndeterminate

Type

boolean

Description

Whether the progress bar is indeterminate

max

Type

number

Description

The maximum value of the progress bar.

min

Type

number

Description

The minimum value of the progress bar.

setValue

Type

(
  value: number,
) => void

Description

Sets the value of the progress bar.

state

Type

| 'indeterminate'
| 'complete'
| 'loading'

Description

The computed state of the progress bar, based on the value.

value

Type

number

Description

The current value of the progress bar.

valuePercent

Type

number

Description

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.

Prop	Type	Default
children React children prop.	ReactNode
defaultValue The initial value of the progress when it is first rendered. Use when you do not need to control the state of the progress.	number
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
emphasis Governs the color of the progress circle.	\| 'primary' \| 'neutral'	'primary'
ids The element ids that are associated with the progress. These will be automatically generated if omitted.	Partial<{ errorText: string hint: string label: string progress: string }>
invalid If `true`, the progress is marked as invalid.	boolean
max Maximum value.	number	100
min Minimum value.	number	0
onValueChange Callback fired when the value changes.	( value: number \| undefined, ) => void
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size Governs the height of the progress circle and track.	\| 'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number	'md'
thickness 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.	\| string \| number
value The value of the progress. If omitted, the component will render as an indefinite progress bar.	number

children

Type

ReactNode

Description

React children prop.

defaultValue

Type

number

Description

The initial value of the progress when it is first rendered. Use when you do not need to control the state of the progress.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

emphasis

Type

| 'primary'
| 'neutral'

Description

Governs the color of the progress circle.

ids

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.

invalid

Type

boolean

Description

If true, the progress is marked as invalid.

max

Type

number

Description

Maximum value.

min

Type

number

Description

Minimum value.

onValueChange

Type

(
  value: number | undefined,
) => void

Description

Callback fired when the value changes.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

size

Type

| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number

Description

Governs the height of the progress circle and track.

thickness

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.

value

Type

number

Description

The value of the progress. If omitted, the component will render as an indefinite progress bar.

Attribute / Property	Value
`className`	'qui-progress-ring__root'
`data-invalid`
`data-max`	number
`data-part`	'root'
`data-scope`	'progress'
`data-size`	\| 'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'
`data-value`	number
`style`	CSSProperties

className

Value

'qui-progress-ring__root'

data-invalid

Value

data-max

Value

number

data-part

Value

'root'

data-scope

Value

'progress'

data-size

Value

| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number

data-state

Value

| 'indeterminate'
| 'complete'
| 'loading'

data-value

Value

number

style

Value

CSSProperties

<ProgressRing.Label>

Label text associated with the progress ring. Renders a <label> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-progress-ring__label'
`data-part`	'label'
`data-scope`	'progress'

<ProgressRing.ValueText>

Displays the current progress value as text. Only visible when size is lg or xl. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-progress-ring__value-text'
`data-invalid`
`data-part`	'value-text'
`data-scope`	'progress'
`hidden`	boolean

className

Value

'qui-progress-ring__value-text'

data-invalid

Value

data-part

Value

'value-text'

data-scope

Value

'progress'

hidden

Value

boolean

<ProgressRing.ErrorText>

Error message displayed when the progress ring is in an invalid state. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-progress-ring__error-text'
`data-part`	'error-text'
`data-scope`	'progress'
`hidden`	boolean

className

Value

'qui-progress-ring__error-text'

data-part

Value

'error-text'

data-scope

Value

'progress'

hidden

Value

boolean

<ProgressRing.CircleContainer>

Container element that wraps the circle and value text. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-progress-ring__circle-container'
`data-part`	'circle-container'
`data-scope`	'progress'

className

Value

'qui-progress-ring__circle-container'

data-part

Value

'circle-container'

data-scope

Value

'progress'

<ProgressRing.Circle>

The SVG element that contains the track and bar. Renders an <svg> element.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

Attribute / Property	Value
`className`	'qui-progress-ring__circle'
`data-emphasis`	\| 'primary' \| 'neutral'
`data-part`	'circle'
`data-scope`	'progress'
`data-size`	\| 'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'
`style`	CSSProperties

className

Value

'qui-progress-ring__circle'

data-emphasis

Value

| 'primary'
| 'neutral'

data-part

Value

'circle'

data-scope

Value

'progress'

data-size

Value

| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number

data-state

Value

| 'indeterminate'
| 'complete'
| 'loading'

style

Value

CSSProperties

<ProgressRing.Track>

The background track of the progress ring. Renders a <circle> element.

Attribute / Property	Value
`className`	'qui-progress-ring__track'
`data-part`	'circle-track'
`data-scope`	'progress'
`data-size`	\| 'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'

className

Value

'qui-progress-ring__track'

data-part

Value

'circle-track'

data-scope

Value

'progress'

data-size

Value

| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number

data-state

Value

| 'indeterminate'
| 'complete'
| 'loading'

<ProgressRing.Bar>

The filled portion of the progress ring that represents the current progress value. Renders a <circle> element.

Attribute / Property	Value
`className`	'qui-progress-ring__bar'
`data-emphasis`	\| 'primary' \| 'neutral'
`data-invalid`
`data-max`	number
`data-part`	'circle-bar'
`data-scope`	'progress'
`data-size`	\| 'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'
`style`	CSSProperties

className

Value

'qui-progress-ring__bar'

data-emphasis

Value

| 'primary'
| 'neutral'

data-invalid

Value

data-max

Value

number

data-part

Value

'circle-bar'

data-scope

Value

'progress'

data-size

Value

| 'xxs'
| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| number

data-state

Value

| 'indeterminate'
| 'complete'
| 'loading'

style

Value

CSSProperties

Progress

Toast Notification