Getting Started
Installation
Theming & Patterns
Composition
Polymorphic ComponentsRender Props
Components
Overview
Buttons
ButtonButton GroupIcon ButtonInline Icon Button
Form Controls
CheckboxComboboxNumber InputPassword InputRadioSelectSliderSwitchText AreaText Input
Data Display
AvatarDividerHeader BarIconLinkSegmented ControlTableTag
Overlays
DialogDrawerMenuPopoverTooltip
Disclosure
AccordionBreadcrumbsCollapsiblePaginationSide NavTabsTree
Feedback
Inline NotificationProgressProgress RingToast Notification

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

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

Emphasis (Color)

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

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.

API

<Progress>

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

PropType
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

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

          <Progress.Label>

          Label for the progress indicator. Renders a <div> element by default.
          PropType
          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.
          id
          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

          <Progress.ErrorText>

          Error text displayed when the progress is in an invalid state. Renders a styled error text element.
          PropType
          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.
          id
          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

          <Progress.Hint>

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

          <Progress.ValueText>

          Text that displays the progress value. Renders a <div> element by default.
          PropType
          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

          <Progress.Track>

          Container for the progress bar. Renders a <div> element by default.
          PropTypeDefault
          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.
          id
          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

          <Progress.Bar>

          Visual indicator that shows progress completion. Renders a <div> element by default.
          PropType
          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
          Inline Notification
          Progress Ring
          Overview
          Examples
          Simple
          Composite
          Label Orientation
          Sizes
          Emphasis (Color)
          Error Text
          Shortcuts
          Track and Bar
          Accessibility
          API
          <Progress>
          ProgressApi
          Composite API
          <Progress.Root>
          <Progress.Label>
          <Progress.ErrorText>
          <Progress.Hint>
          <Progress.ValueText>
          <Progress.Track>
          <Progress.Bar>
          Copyright © 2026 QUALCOMM incorporated. All rights reserved. This site is built with QUI Docs. Head over to the template repository to start building.