Search docs

Progress

The progress of a task, determinate or indeterminate.

There is no WAI-ARIA APG pattern for progress bars. Progress renders a <div> with the progressbar role. Use Meter for a value that goes up and down within a range, such as disk usage.

Uploading40%
import { component$, useStyles$ } from '@builder.io/qwik';
import { Progress } from '@leve-ui/progress';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Progress.Root value={40} class="progress-default">
      <Progress.Label class="progress-default-label">Uploading</Progress.Label>
      <Progress.ValueText class="progress-default-value" />
      <Progress.Track class="progress-default-track">
        <Progress.Indicator class="progress-default-indicator" />
      </Progress.Track>
    </Progress.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/progress

Anatomy#

import { Progress } from '@leve-ui/progress'; // or '@leve-ui/core'

<Progress.Root>
  <Progress.Label />
  <Progress.ValueText />
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
PartElementDescription
Progress.Root<div>The progress bar, with role="progressbar". Holds the value and the range.
Progress.Label<span>The label. Names the Root.
Progress.ValueText<span>Shows the value text (by default, the percentage).
Progress.Track<div>The whole range. Contains the Indicator.
Progress.Indicator<div>The current value. Exposes the percentage as a CSS variable.

Examples#

Controlled#

The value follows a signal. The state becomes "complete" when the value reaches max.

Uploading0%

Indeterminate#

value={null} (the default) means the progress is unknown. The state is "indeterminate", and the CSS animates the Indicator with [data-state="indeterminate"].

Uploading

With Value Text#

valueText replaces the percentage with a human-readable text. It is shown by Progress.ValueText and used as aria-valuetext.

Uploading3 of 10 files

API Reference#

Root#

PropDefaultType
valuenullnumber | null

The current value. null means the progress is indeterminate.

min0number

The minimum value.

max100number

The maximum value.

valueText–string

A human-readable text for the value (e.g. "3 / 10 files"), used for aria-valuetext and shown by ValueText. Defaults to the percentage (e.g. "30%").

Also accepts all <div> attributes.

Data attributeValue
data-leve-progressAlways present
data-state"indeterminate" | "loading" | "complete"
data-valueThe value, clamped between min and max. Absent when indeterminate
data-minThe min value
data-maxThe max value

data-state is "indeterminate" when value is null, "complete" when the value reaches max, and "loading" otherwise.

Label#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-progress-labelAlways present
data-state"indeterminate" | "loading" | "complete"
data-valueThe clamped value. Absent when indeterminate
data-minThe min value
data-maxThe max value

The Label gets a generated id that the Root references with aria-labelledby. If you pass your own id, also pass the same value as aria-labelledby to the Root.

ValueText#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-progress-value-textAlways present
data-state"indeterminate" | "loading" | "complete"
data-valueThe clamped value. Absent when indeterminate
data-minThe min value
data-maxThe max value

Renders the Root's valueText, or the rounded percentage (for example "40%") when it is not set. When indeterminate and valueText is not set, it is empty. It has no children.

Track#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-progress-trackAlways present
data-state"indeterminate" | "loading" | "complete"
data-valueThe clamped value. Absent when indeterminate
data-minThe min value
data-maxThe max value

Indicator#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-progress-indicatorAlways present
data-state"indeterminate" | "loading" | "complete"
data-valueThe clamped value. Absent when indeterminate
data-minThe min value
data-maxThe max value
CSS variableValue
--leve-progress-percentThe value as a percentage of the range, for example 40%. Not set when indeterminate

The library does not set a width. Use the variable yourself, for example width: var(--leve-progress-percent).

Accessibility#

  • Progress.Root renders role="progressbar" with aria-valuemin and aria-valuemax, aria-valuenow unless indeterminate, and aria-valuetext when valueText is set.
  • The Root is named by Progress.Label through aria-labelledby. If you pass aria-label or aria-labelledby to the Root, that is used instead.
  • When the percentage alone does not describe the progress (for example, "3 of 10 files"), set valueText.
  • Progress has no keyboard interaction.