Progress | QUI

Overview

The progress bar 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.

Determinate progress bars display a shimmer effect across the filled portion while loading after 8 seconds. It is suppressed for users who prefer reduced motion. Set the shimmer prop to false to turn it off.

Examples

Simple

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

Indeterminate

Determinate

64%

Optional hint

<div class="w-64" label="Indeterminate" q-progress></div>
<div
  hint="Optional hint"
  label="Determinate"
  q-progress
  value="64"
  valueText="64%"
></div>

Child Directives

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

Label

<div class="w-64" q-progress>
  <div q-progress-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.

Label

64%

Optional hint

<div class="w-64" q-progress-root value="64">
  <div q-progress-label>Label</div>
  <div *progressContext="let context" q-progress-value-text>
    <div q-progress-value-text>{{ context.valuePercent }}%</div>
  </div>
  <div q-progress-track></div>
  <div q-progress-error-text></div>
  <div q-progress-hint>Optional hint</div>
</div>

Label Orientation

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

Label

64%

<div
  class="w-96"
  label="Label"
  labelOrientation="side"
  q-progress
  value="64"
  valueText="64%"
></div>

Sizes

sm

md

lg

<div label="sm" q-progress size="sm" [value]="value()"></div>
<div label="md" q-progress size="md" [value]="value()"></div>
<div label="lg" q-progress size="lg" [value]="value()"></div>

Emphasis (Color)

<div emphasis="primary" q-progress></div>
<div emphasis="neutral" q-progress></div>

Disabled

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

Indeterminate

Determinate

64%

<div class="w-64" disabled label="Indeterminate" q-progress></div>
<div
  class="w-64"
  disabled
  label="Determinate"
  q-progress
  value="64"
  valueText="64%"
></div>

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

<div
  class="w-64"
  defaultValue="25"
  errorText="Network disconnected, please try again"
  invalid
  label="Loading Module"
  q-progress
>
  <div *progressContext="let context" q-progress-value-text>
    {{ context.valuePercent }}%
  </div>
</div>

Shortcuts

Track and Bar

The q-progress-track automatically renders a q-progress-bar when no children as passed to it. This makes <div q-progress-track></div> equivalent to:

<div q-progress-track>
  <div q-progress-bar></div>
</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 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

Component Anatomy

Hover to highlight, click to view API

root label track bar value-text hint

API

q-progress

The q-progress directive extends the q-progress-root directive with the following properties:

Prop	Type
errorText Optional error text. Only rendered when invalid is true.	string

hint Additional description for the component, rendered below the bar.	string

label Accessible label for the component, rendered above or to the left of the bar.	string

valueText Optional value text.	string

errorText

Type

string

Description

Optional error text. Only rendered when invalid is true.

hint

Type

string

Description

Additional description for the component, rendered below the bar.

label

Type

string

Description

Accessible label for the component, rendered above or to the left of the bar.

valueText

Type

string

Description

Optional value text.

ProgressApi

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

<ng-container *progressContext="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-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 bar.	\| 'primary' \| 'neutral'	'primary'
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
shimmer Whether to display a shimmer effect on a loading determinate progress.	boolean	true
size Governs the height of the progress bar and track.	\| 'sm' \| 'md' \| 'lg'	'md'
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 bar.

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

shimmer

Type

boolean

Description

Whether to display a shimmer effect on a loading determinate progress.

size

Type

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

Description

Governs the height of the progress bar and track.

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

class

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

q-progress-label

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

id

Type

string

Description

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

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

q-progress-error-text

Prop	Type	Default
icon Error indicator icon.	\| LucideIcon \| LucideIconData \| string	LucideCircleAlert
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

icon

Type

| LucideIcon
| LucideIconData
| string

Description

Error indicator icon.

id

Type

string

Description

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

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

q-progress-hint

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

id

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-progress__hint'
`data-progress-part`	'hint'
`hidden`	boolean

q-progress-value-text

Attribute / Property	Value
`class`	'qui-progress__value-text'
`data-invalid`
`data-progress-part`	'value-text'

q-progress-track

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

id

Type

string

Description

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

Attribute / Property	Value
`class`	'qui-progress__track'
`data-disabled`
`data-progress-part`	'track'
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'

class

Value

'qui-progress__track'

data-disabled

Value

data-progress-part

Value

'track'

data-size

Value

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

data-state

Value

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

q-progress-bar

Attribute / Property	Value
`class`	'qui-progress__bar'
`data-disabled`
`data-emphasis`	\| 'primary' \| 'neutral'
`data-invalid`
`data-max`	number
`data-progress-part`	'bar'
`data-shimmer`
`data-size`	\| 'sm' \| 'md' \| 'lg'
`data-state`	\| 'indeterminate' \| 'complete' \| 'loading'

class

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

Value

data-size

Value

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

data-state

Value

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