Progress Circle

Progress circles show the progression of an operation in a visual way.

import {QProgressCircle} from "@qui/react"

Accessibility

When the value is supplied, we provide the corresponding aria-value* attributes to the element.
According to ARIA guidelines, the progress circle must have an accessible name. You should provide an accessible name using the aria-label or aria-labelledby attributes.

// aria-label
<QProgressCircle aria-label="Loading Profile" />

// OR aria-labelledby
<label id="loading-indicator-label">Loading</label>
<QProgressCircle aria-labelledby="loading-indicator-label" />

Examples

Determinate

A determinate progress circle displays the exact percentage of completion of the operation. Pass a value between 0 and 100 to the value input to indicate an operation's progress.

import {ReactNode, useEffect, useState} from "react"

import {QProgressCircle} from "@qui/react"

export default function Determinate(): ReactNode {
  const [value, setValue] = useState<number>(0)

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((currentValue) => (currentValue >= 100 ? 0 : currentValue + 5))
    }, 1000)
    return () => clearInterval(interval)
  }, [])

  return (
    <div className="grid justify-center p-4">
      <QProgressCircle aria-label="Loading" showValueLabel value={value} />
    </div>
  )
}

If no value is specified, the progress circle will not display any percentage of completion, and will instead render as indeterminate. This is indicated by a spinner that is constantly moving. These can be used to indicate ongoing processes with an undetermined wait time.

import {ReactNode} from "react"

import {QProgressCircle} from "@qui/react"

export default function Indeterminate(): ReactNode {
  return <QProgressCircle aria-label="Loading" />
}

Value Label

Add a value label for the progress circle by setting the showValueLabel input to true. The label will render inside the progress spinner. This is only available for progress circles larger than 48px (m, l, or a custom size).

import {ReactNode, useEffect, useState} from "react"

import {QProgressCircle} from "@qui/react"

export default function Label(): ReactNode {
  const [value, setValue] = useState<number>(0)

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((currentValue) => (currentValue >= 100 ? 0 : currentValue + 5))
    }, 1000)
    return () => clearInterval(interval)
  }, [])

  return (
    <div className="flex justify-center gap-16">
      <QProgressCircle aria-label="Loading" value={value} />

      <QProgressCircle aria-label="Loading" showValueLabel value={value} />
    </div>
  )
}

Sizes

The progress circle is available in five sizes: xxs, xs, s, m (default) and l. Should you need to fine tune the exact size, supply a number instead which will be converted to pixels.

DeterminateIndeterminateExtra Extra Small (xxs)Extra Small (xs)Small (s)Medium (m)0%Large (l)0%Custom0%

import {ReactNode, useEffect, useState} from "react"

import {QProgressCircle} from "@qui/react"

export default function Size(): ReactNode {
  const [value, setValue] = useState<number>(0)

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((currentValue) => (currentValue >= 100 ? 0 : currentValue + 5))
    }, 1000)
    return () => clearInterval(interval)
  }, [])

  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-3 items-center justify-items-center gap-x-20 gap-y-4">
        <span />
        <span className="mt-4 text-primary q-font-heading-xs">Determinate</span>
        <span className="mt-4 text-primary q-font-heading-xs">
          Indeterminate
        </span>

        <span className="text-primary q-font-heading-xs">
          Extra Extra Small (xxs)
        </span>
        <QProgressCircle aria-label="Loading" size="xxs" value={value} />
        <QProgressCircle aria-label="Loading" size="xxs" />

        <span className="text-primary q-font-heading-xs">Extra Small (xs)</span>
        <QProgressCircle aria-label="Loading" size="xs" value={value} />
        <QProgressCircle aria-label="Loading" size="xs" />

        <span className="text-primary q-font-heading-xs">Small (s)</span>
        <QProgressCircle aria-label="Loading" size="s" value={value} />
        <QProgressCircle aria-label="Loading" size="s" />

        <span className="text-primary q-font-heading-xs">Medium (m)</span>
        <QProgressCircle aria-label="Loading" showValueLabel value={value} />
        <QProgressCircle aria-label="Loading" />

        <span className="text-primary q-font-heading-xs">Large (l)</span>
        <QProgressCircle
          aria-label="Loading"
          showValueLabel
          size="l"
          value={value}
        />
        <QProgressCircle aria-label="Loading" size="l" />

        <span className="text-primary q-font-heading-xs">Custom</span>
        <QProgressCircle
          aria-label="Loading"
          showValueLabel
          size={100}
          value={value}
        />
        <QProgressCircle aria-label="Loading" size={100} />
      </div>
    </div>
  )
}

API

Props

Name & Description	Option(s)	Default
as The component used for the root node. It can be a React component or element.	\| ElementType \| ComponentType	'span'
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
color The color applied to the filled segment of the circle.	string	'var(--q-brand-600)'
showValueLabel If true and the value input is supplied, the current progress percentage will be indicated by a label.	boolean	false
size Size of the progress circle.	\| 'xxs' \| 'xs' \| 's' \| 'm' \| 'l' \| number	'm'
strokeWidth The stroke width of the progress circle. If omitted, this will be computed dynamically based on the value of size. This typically doesn't need to be configured.	number
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
value Value of the progress circle. If this value is omitted, the progress circle will be indeterminate.	number

Type

| ElementType
| ComponentType

Default

'span'

Description

The component used for the root node. It can be a React component or element.

className

Type

string

Description

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

color

Type

string

Default

'var(--q-brand-600)'

Description

The color applied to the filled segment of the circle.

showValueLabel

Type

boolean

Default

false

Description

If true and the value input is supplied, the current progress percentage will be indicated by a label.

size

Type

| 'xxs'
| 'xs'
| 's'
| 'm'
| 'l'
| number

Default

'm'

Description

Size of the progress circle.

strokeWidth

Type

number

Description

The stroke width of the progress circle. If omitted, this will be computed dynamically based on the value of size. This typically doesn't need to be configured.

style

Type

CSSProperties

Description

The style global attribute contains CSS styling declarations to be applied to the element.

value

Type

number

Description

Value of the progress circle. If this value is omitted, the progress circle will be indeterminate.

Progress Bar

Radio