Progress Ring

A small visual indicator that communicates ongoing task execution.

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.

Brand

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.

Brand

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.

Brand

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

Brand

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

Brand

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

<div class="py-2" q-progress-ring size="lg" [thickness]="8"></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.

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

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.

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

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

class

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

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-part`	'label'
`data-scope`	'progress'

q-progress-ring-value-text

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

class

Value

'qui-progress-ring__value-text'

data-invalid

Value

data-part

Value

'value-text'

data-scope

Value

'progress'

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

class

Value

'qui-progress-ring__error-text'

data-part

Value

'error-text'

data-scope

Value

'progress'

hidden

Value

boolean

q-progress-ring-circle-container

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

class

Value

'qui-progress-ring__circle-container'

data-part

Value

'circle-container'

data-scope

Value

'progress'

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

class

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

q-progress-ring-track

Attribute / Property	Value
`class`	'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'

class

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'

q-progress-ring-bar

Attribute / Property	Value
`class`	'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

class

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