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 {ProgressRingModule} from "@qualcomm-ui/angular/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

The simple API bundles all subcomponents together into a single directive.

Label

<div label="Label" q-progress-ring></div>

Child Directives

Provide child directives to customize specific elements while keeping the simple API's default structure.

Label

<div q-progress-ring>
  <div q-progress-ring-label>Label</div>
</div>

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.

<div q-progress-ring-root>
  <div q-progress-ring-circle-container>
    <svg q-progress-ring-circle></svg>
  </div>
  <div q-progress-ring-label>Loading...</div>
</div>

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

<div q-progress-ring size="lg" [value]="value()">
  <svg aria-label="Loading" q-progress-ring-circle></svg>
  <div *progressRingContext="let context" q-progress-ring-value-text>
    {{ context.valuePercent }}%
  </div>
</div>

Value Text

Display the value text using the q-progress-ring-value-text directive. The value text only shows when the size is lg or xl.

10%

import {Component, type OnInit, signal} from "@angular/core"

import {useOnDestroy} from "@qualcomm-ui/angular-core/common"
import {ProgressRingModule} from "@qualcomm-ui/angular/progress-ring"

@Component({
  imports: [ProgressRingModule],
  selector: "progress-ring-value-text-demo",
  template: `
    <div label="Loading..." q-progress-ring size="lg" [value]="value()">
      <div *progressRingContext="let context" q-progress-ring-value-text>
        {{ context.valuePercent }}%
      </div>
    </div>
  `,
})
export class ProgressRingValueTextDemo implements OnInit {
  protected readonly onDestroy = useOnDestroy()
  protected readonly value = signal(0)

  ngOnInit() {
    const timer = setInterval(() => {
      this.value.update((prevValue) => {
        if (prevValue === 100) {
          return 0
        }
        return prevValue + 10
      })
    }, 1000)

    this.onDestroy(() => {
      clearInterval(timer)
    })
  }
}

Sizes

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

xxs

import {Component, type OnInit, signal} from "@angular/core"

import {useOnDestroy} from "@qualcomm-ui/angular-core/common"
import {ProgressRingModule} from "@qualcomm-ui/angular/progress-ring"

@Component({
  imports: [ProgressRingModule],
  selector: "progress-ring-sizes-demo",
  template: `
    <div class="flex items-center gap-4">
      <div
        class="grid grid-cols-3 items-center justify-items-center gap-x-8 gap-y-4"
      >
        <div class="font-heading-xs text-neutral-primary">xxs</div>
        <div q-progress-ring size="xxs" [value]="value()"></div>
        <div q-progress-ring size="xxs"></div>

        <div class="font-heading-xs text-neutral-primary">xs</div>
        <div q-progress-ring size="xs" [value]="value()"></div>
        <div q-progress-ring size="xs"></div>

        <div class="font-heading-xs text-neutral-primary">sm</div>
        <div q-progress-ring size="sm" [value]="value()"></div>
        <div q-progress-ring size="sm"></div>

        <div class="font-heading-xs text-neutral-primary">md</div>
        <div q-progress-ring size="md" [value]="value()"></div>
        <div q-progress-ring size="md"></div>

        <div class="font-heading-xs text-neutral-primary">lg</div>
        <div q-progress-ring size="lg" [value]="value()"></div>
        <div q-progress-ring size="lg"></div>

        <div class="font-heading-xs text-neutral-primary">xl</div>
        <div q-progress-ring size="xl" [value]="value()"></div>
        <div q-progress-ring size="xl"></div>
      </div>
    </div>
  `,
})
export class ProgressRingSizesDemo implements OnInit {
  protected readonly onDestroy = useOnDestroy()
  protected readonly value = signal(0)

  ngOnInit() {
    const timer = setInterval(() => {
      this.value.update((prevValue) => {
        if (prevValue === 100) {
          return 0
        }
        return prevValue + 10
      })
    }, 1000)

    this.onDestroy(() => {
      clearInterval(timer)
    })
  }
}

Thickness

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

<div class="py-2" q-progress-ring size="lg" [thickness]="8"></div>

Disabled

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

Indeterminate

64%

Determinate

<div disabled label="Indeterminate" q-progress-ring size="lg"></div>
<div
  disabled
  label="Determinate"
  q-progress-ring
  size="lg"
  value="64"
  valueText="64%"
></div>

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

Explorer

Component Anatomy

Hover to highlight, click to view API

root label circle-container circle-track circle-bar value-text

API

q-progress-ring

The q-progress-ring extends the q-progress-ring-root with the following props:

Prop	Type
errorText Error text rendered below the progress ring when invalid is true.	string

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

valueText Optional value text displayed inside the progress ring.	string

errorText

Type

string

Description

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

label

Type

string

Description

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

valueText

Type

string

Description

Optional value text displayed inside the progress ring.

ProgressApi

The ProgressApi is accessible from the template via the progressRingContext structural directive:

<ng-container *progressRingContext="let context">
  {{ context.valuePercent }}%
</ng-container>

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

q-progress-ring-root

Prop	Type	Default
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 circle.	\| 'primary' \| 'neutral'	'primary'
invalid If `true`, the progress is marked as invalid.	boolean
max Maximum value	number	100
min Minimum value	number	0
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 Current progress value (0-100)	number
(valueChanged) Callback fired when the value changes.	number

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

invalid

Type

boolean

Description

If true, the progress is marked as invalid.

max

Type

number

Description

Maximum value

min

Type

number

Description

Minimum value

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

Current progress value (0-100)

(valueChanged)

Type

number

Description

Callback fired when the value changes.

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

class

Value

'qui-progress-ring__root'

data-disabled

Value

data-invalid

Value

data-max

Value

number

data-progress-part

Value

'root'

data-size

Value

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

data-state

Value

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

data-value

Value

number

style

Value

CSSProperties

q-progress-ring-label

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

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

q-progress-ring-value-text

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

class

Value

'qui-progress-ring__value-text'

data-invalid

Value

data-progress-part

Value

'value-text'

hidden

Value

boolean

q-progress-ring-error-text

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

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

q-progress-ring-circle-container

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

q-progress-ring-circle

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

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

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

class

Value

'qui-progress-ring__circle'

data-disabled

Value

data-emphasis

Value

| 'primary'
| 'neutral'

data-progress-part

Value

'circle'

data-size

Value

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

data-state

Value

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

style

Value

CSSProperties

q-progress-ring-track

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

class

Value

'qui-progress-ring__track'

data-disabled

Value

data-progress-part

Value

'circle-track'

data-size

Value

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

data-state

Value

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

q-progress-ring-bar

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

class

Value

'qui-progress-ring__bar'

data-disabled

Value

data-emphasis

Value

| 'primary'
| 'neutral'

data-invalid

Value

data-max

Value

number

data-progress-part

Value

'circle-bar'

data-size

Value

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

data-state

Value

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

style

Value

CSSProperties

Last updated on Apr 24, 2026 by Olaf Kappes

Progress

Radio