Progress

Progress bars provide clear visual feedback about task completion or loading states, helping users understand system status and perceived remaining time.

import {Progress} from "@qualcomm-ui/react/progress"

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 bars keep users informed that work is happening when timeframes are unknown.

Examples

Simple

The simple API provides a standalone component with built-in layout.

Indeterminate

Determinate

64%

Optional hint

<Progress className="w-64" label="Indeterminate" />
<Progress
  hint="Optional hint"
  label="Determinate"
  value={64}
  valueText="64%"
/>

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.

Label

64%

Optional hint

<Progress.Root className="w-64" value={64}>
  <Progress.Label>Label</Progress.Label>
  <Progress.Context>
    {(api) => (
      <Progress.ValueText>{`${api.valuePercent}%`}</Progress.ValueText>
    )}
  </Progress.Context>
  <Progress.ValueText />
  <Progress.Track />
  <Progress.Hint>Optional hint</Progress.Hint>
</Progress.Root>

Label Orientation

Use the labelOrientation property to change the positioning of the label and value text relative to the progress bar.

Determinate

64%

import type {ReactElement} from "react"

import {Progress} from "@qualcomm-ui/react/progress"

export function ProgressLabelOrientationDemo(): ReactElement {
  return (
    <div className="flex flex-col gap-6">
      <Progress
        className="w-96"
        label="Determinate"
        labelOrientation="side"
        value={64}
        valueText="64%"
      />
    </div>
  )
}

Sizes

Progress bars support three sizes: sm, md, and lg.

<Progress label="sm" size="sm" value={value} />
<Progress label="md" size="md" value={value} />
<Progress label="lg" size="lg" value={value} />

Emphasis (Color)

Set the color of the progress bar using the emphasis property. The available options are primary and neutral.

<Progress emphasis="primary" />
<Progress emphasis="neutral" />

Disabled

Use the disabled prop to indicate that the progress indicator is inactive.

Indeterminate

Determinate

64%

<Progress className="w-64" disabled label="Indeterminate" />
<Progress
  className="w-64"
  disabled
  label="Determinate"
  value={64}
  valueText="64%"
/>

Error Text

Error messages are displayed using two props:

invalid
errorText (or the Progress.ErrorText component when using the composite API)

The error text will only render when invalid is true.

Loading Module

25%

Network disconnected, please try again

<Progress
  className="w-64"
  defaultValue={25}
  errorText="Network disconnected, please try again"
  invalid
  label="Loading Module"
  valueText={({valuePercent}) => `${valuePercent}%`}
/>

Shortcuts

Track and Bar

The Progress.Track automatically renders a Progress.Bar when no children as passed to it.

<Progress.Track />

is equivalent to

<Progress.Track>
  <Progress.Bar />
</Progress.Track>

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.

Explorer

Uploading

64%

Some contextual help here

Component Anatomy

Hover to highlight, click to view API

root label track bar value-text hint

API

<Progress>

The Progress component supports all props from Progress.Root, plus the additional props listed below.

Prop	Type
barProps Props passed to the progress bar.	ProgressBarProps
errorText Error text rendered when invalid is true.	ReactNode
errorTextProps Props passed to the error text element.	ProgressErrorTextProps
hint Optional hint text rendered below the progress bar.	ReactNode
hintProps Props passed to the hint element.	ProgressHintProps
label The progress label.	ReactNode
labelProps Props passed to the progress label.	ProgressLabelProps
trackProps Props passed to the progress track.	ProgressTrackProps
valueText Value text Render Prop	BindingRenderProp< ProgressApi, ReactNode >
valueTextProps Props passed to the value text.	ProgressValueTextProps

barProps

Type

ProgressBarProps

Description

Props passed to the progress bar.

errorText

Type

ReactNode

Description

Error text rendered when invalid is true.

errorTextProps

Type

ProgressErrorTextProps

Description

Props passed to the error text element.

hint

Type

ReactNode

Description

Optional hint text rendered below the progress bar.

hintProps

Type

ProgressHintProps

Description

Props passed to the hint element.

label

Type

ReactNode

Description

The progress label.

labelProps

Type

ProgressLabelProps

Description

Props passed to the progress label.

trackProps

Type

ProgressTrackProps

Description

Props passed to the progress track.

valueText

Type

BindingRenderProp<
  ProgressApi,
  ReactNode
>

Description

Value text Render Prop

valueTextProps

Type

ProgressValueTextProps

Description

Props passed to the value text.

ProgressApi

This API is accessible in JSX via the <Progress.Context> component:

<Progress.Context>
  {(api: ProgressApi) => {
    return <>{/*...*/}</>
  }}
</Progress.Context>

Learn more about this pattern: Render Props

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

<Progress.Root>

Root container for a progress indicator. 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'
disabled If `true`, the progress is disabled.	boolean
emphasis Governs the color of the progress bar.	\| '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
labelOrientation Governs the placement of the label and value text relative to the progress bar. `top`: the label and value text are positioned above the progress bar. `side`: the label and value text are positioned on the same horizontal axis as the progress bar, to the left and right, respectively.	'top' \| 'side'	'top'
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 bar and track.	\| 'sm' \| 'md' \| 'lg'	'md'
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.

disabled

Type

boolean

Description

If true, the progress is disabled.

emphasis

Type

| 'primary'
| 'neutral'

Description

Governs the color of the progress bar.

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.

labelOrientation

Type

'top' | 'side'

Description

Governs the placement of the label and value text relative to the progress bar.

top: the label and value text are positioned above the progress bar.
side: the label and value text are positioned on the same horizontal axis as the progress bar, to the left and right, respectively.

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

| 'sm'
| 'md'
| 'lg'

Description

Governs the height of the progress bar and track.

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__root'
`data-disabled`
`data-invalid`
`data-label-orientation`	'top' \| 'side'
`data-max`	number
`data-progress-part`	'root'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'
`data-value`	number
`style`	CSSProperties

className

Value

'qui-progress__root'

data-disabled

Value

data-invalid

Value

data-label-orientation

Value

'top' | 'side'

data-max

Value

number

data-progress-part

Value

'root'

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

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

data-value

Value

number

style

Value

CSSProperties

<Progress.Label>

Label for the progress indicator. 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__label'
`data-progress-part`	'label'

<Progress.ErrorText>

Error text displayed when the progress is in an invalid state. Renders a styled error text element.

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__error-text'
`data-progress-part`	'error-text'
`hidden`	boolean

<Progress.Hint>

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__hint'
`data-progress-part`	'hint'
`hidden`	boolean

<Progress.ValueText>

Text that displays the progress value. 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__value-text'
`data-invalid`
`data-progress-part`	'value-text'

<Progress.Track>

Container for the progress bar. Renders a <div> element by default.

Prop	Type	Default
children React children prop.	ReactNode	<ProgressBar />
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__track'
`data-disabled`
`data-progress-part`	'track'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'

className

Value

'qui-progress__track'

data-disabled

Value

data-progress-part

Value

'track'

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

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

<Progress.Bar>

Visual indicator that shows progress completion. 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__bar'
`data-disabled`
`data-emphasis`	\| 'primary' \| 'neutral'
`data-invalid`
`data-max`	number
`data-progress-part`	'bar'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'
`style`	CSSProperties

className

Value

'qui-progress__bar'

data-disabled

Value

data-emphasis

Value

| 'primary'
| 'neutral'

data-invalid

Value

data-max

Value

number

data-progress-part

Value

'bar'

data-size

Value

| 'sm'
| 'md'
| 'lg'

data-state

Value

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

style

Value

CSSProperties

Last updated on May 23, 2026 by Ryan Bower

Popover

Progress Ring