Progress Bar

Progress bars are used to provide feedback to users about the duration and progression of a process.

import {QProgressBar} from "@qui/react"

Overview

Progress bars can help to reduce user anxiety by providing a visual indication of how long a user will be waiting.
Progress bars can also be used to provide a sense of accomplishment by showing users how much progress they have made towards completing a task.

Accessibility

When the value is supplied, we provide the corresponding aria-value* attributes to the element.
According to ARIA guidelines, the progress bar must have an accessible name. When you supply the label prop, we automatically associate it with the progress bar element. If you omit the label, you should provide an accessible name using the aria-label attribute.

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

Examples

Determinate

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

Loading...0%

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

import {QProgressBar} 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">
      <div className="flex w-[300px] p-4">
        <QProgressBar
          aria-label="Loading Indicator"
          label="Loading..."
          showValueLabel
          value={value}
        />
      </div>
    </div>
  )
}

Indeterminate

If no value is specified, the progress bar will not display any percentage of completion, and will instead render as indeterminate. This is indicated by a bar that is constantly moving.

Processing...

import {ReactNode} from "react"

import {QProgressBar} from "@qui/react"

export default function Indeterminate(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="flex w-[300px] p-4">
        <QProgressBar label="Processing..." />
      </div>
    </div>
  )
}

Add a descriptor for the progress bar by passing a label property. The label will render above the progress bar by default. Change this by setting the labelPosition property to side. To show the value label, set the showValueLabel property to true.

No Label (default)

Processing...

Top Label

Loading...0%

Side Label

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

import {QProgressBar} 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="grid justify-center gap-8 p-4">
      <div className="flex w-[300px] flex-col gap-8 p-4">
        <span className="text-primary q-font-heading-xs">
          No Label (default)
        </span>
        <QProgressBar label="Processing..." value={value} />
        <QProgressBar aria-label="Loading" />

        <span className="mt-4 text-primary q-font-heading-xs">Top Label</span>
        <QProgressBar label="Loading..." showValueLabel value={value} />
        <QProgressBar label="Loading..." value={value} />

        <span className="mt-4 text-primary q-font-heading-xs">Side Label</span>

        <QProgressBar label="Loading..." labelPosition="side" value={value} />
        <QProgressBar
          aria-label="Loading"
          labelPosition="side"
          showValueLabel
          value={value}
        />
        <QProgressBar
          label="Loading..."
          labelPosition="side"
          showValueLabel
          value={value}
        />
      </div>
    </div>
  )
}

Sizes

Two sizes are available: m (default) and l

Medium (m)

Large (l)

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

import {QProgressBar} 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="flex w-[300px] flex-col gap-8 p-4">
        <span className="text-primary q-font-heading-xs">Medium (m)</span>
        <QProgressBar aria-label="Loading" value={value} />
        <QProgressBar aria-label="Loading" />

        <span className="text-primary q-font-heading-xs">Large (l)</span>
        <QProgressBar aria-label="Loading" size="l" value={value} />
        <QProgressBar aria-label="Loading" size="l" />
      </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	'div'
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 of filled segment of the progress bar.	string	'var(--q-brand-600)'
label Label for the progress bar.	ReactNode
labelPosition Position of the label.	'top' \| 'side'	'top'
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 bsr.	'm' \| 'l'	'm'
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
value Value of the progress bar. If this value is omitted, the progress bar will be rendered as indeterminate.	number