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.
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>
);
});.progress-default {
display: grid;
grid-template-columns: 1fr auto;
row-gap: 8px;
align-items: center;
width: 240px;
font-family: inherit;
}
.progress-default-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.progress-default-value {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
text-align: right;
}
.progress-default-track {
grid-column: 1 / -1;
height: 8px;
border-radius: 9999px;
background: light-dark(#e2e8f0, #ffffff1f);
overflow: hidden;
}
.progress-default-indicator {
height: 100%;
/* Percentage of the Root value, set by the library */
width: var(--leve-progress-percent);
border-radius: 9999px;
background: #009dfd;
transition: width 200ms ease;
}
@media (prefers-reduced-motion: reduce) {
.progress-default-indicator {
transition: none;
}
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/progressnpm install @leve-ui/progressyarn add @leve-ui/progressbun add @leve-ui/progresspnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { Progress } from '@leve-ui/progress'; // or '@leve-ui/core'
<Progress.Root>
<Progress.Label />
<Progress.ValueText />
<Progress.Track>
<Progress.Indicator />
</Progress.Track>
</Progress.Root>
| Part | Element | Description |
|---|---|---|
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.
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Progress } from '@leve-ui/progress';
import styles from './controlled.css?inline';
export default component$(() => {
useStyles$(styles);
const value = useSignal(0);
return (
<div class="progress-controlled-wrapper">
<Progress.Root value={value.value} class="progress-controlled">
<Progress.Label class="progress-controlled-label">Uploading</Progress.Label>
<Progress.ValueText class="progress-controlled-value" />
<Progress.Track class="progress-controlled-track">
<Progress.Indicator class="progress-controlled-indicator" />
</Progress.Track>
</Progress.Root>
<div class="progress-controlled-buttons">
<button
type="button"
class="progress-controlled-button"
onClick$={() => (value.value = Math.min(value.value + 25, 100))}
>
Advance
</button>
<button type="button" class="progress-controlled-button" onClick$={() => (value.value = 0)}>
Reset
</button>
</div>
</div>
);
});.progress-controlled {
display: grid;
grid-template-columns: 1fr auto;
row-gap: 8px;
align-items: center;
width: 240px;
font-family: inherit;
}
.progress-controlled-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.progress-controlled-value {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
text-align: right;
}
.progress-controlled-track {
grid-column: 1 / -1;
height: 8px;
border-radius: 9999px;
background: light-dark(#e2e8f0, #ffffff1f);
overflow: hidden;
}
.progress-controlled-indicator {
height: 100%;
/* Percentage of the Root value, set by the library */
width: var(--leve-progress-percent);
border-radius: 9999px;
background: #009dfd;
transition: width 200ms ease;
}
@media (prefers-reduced-motion: reduce) {
.progress-controlled-indicator {
transition: none;
}
}
.progress-controlled-wrapper {
display: flex;
flex-direction: column;
gap: 12px;
font-family: inherit;
}
.progress-controlled-buttons {
display: flex;
gap: 8px;
}
.progress-controlled-button {
height: 32px;
padding: 0 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.progress-controlled-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.progress-controlled-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}Indeterminate#
value={null} (the default) means the progress is unknown. The state is "indeterminate", and the CSS animates the Indicator with [data-state="indeterminate"].
import { component$, useStyles$ } from '@builder.io/qwik';
import { Progress } from '@leve-ui/progress';
import styles from './indeterminate.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Progress.Root value={null} class="progress-indeterminate">
<Progress.Label class="progress-indeterminate-label">Uploading</Progress.Label>
<Progress.ValueText class="progress-indeterminate-value" />
<Progress.Track class="progress-indeterminate-track">
<Progress.Indicator class="progress-indeterminate-indicator" />
</Progress.Track>
</Progress.Root>
);
});.progress-indeterminate {
display: grid;
grid-template-columns: 1fr auto;
row-gap: 8px;
align-items: center;
width: 240px;
font-family: inherit;
}
.progress-indeterminate-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.progress-indeterminate-value {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
text-align: right;
}
.progress-indeterminate-track {
grid-column: 1 / -1;
height: 8px;
border-radius: 9999px;
background: light-dark(#e2e8f0, #ffffff1f);
overflow: hidden;
}
.progress-indeterminate-indicator {
height: 100%;
/* Percentage of the Root value, set by the library */
width: var(--leve-progress-percent);
border-radius: 9999px;
background: #009dfd;
transition: width 200ms ease;
}
/* No percentage while indeterminate, so slide a fixed-width bar instead */
.progress-indeterminate-indicator[data-state="indeterminate"] {
width: 40%;
animation: progress-indeterminate-slide 1.2s ease-in-out infinite;
}
@keyframes progress-indeterminate-slide {
from {
transform: translateX(-100%);
}
to {
transform: translateX(250%);
}
}
@media (prefers-reduced-motion: reduce) {
.progress-indeterminate-indicator[data-state="indeterminate"] {
animation: none;
}
}With Value Text#
valueText replaces the percentage with a human-readable text. It is shown by Progress.ValueText and used as aria-valuetext.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Progress } from '@leve-ui/progress';
import styles from './with-value-text.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<Progress.Root value={30} valueText="3 of 10 files" class="progress-with-value-text">
<Progress.Label class="progress-with-value-text-label">Uploading</Progress.Label>
<Progress.ValueText class="progress-with-value-text-value" />
<Progress.Track class="progress-with-value-text-track">
<Progress.Indicator class="progress-with-value-text-indicator" />
</Progress.Track>
</Progress.Root>
);
});.progress-with-value-text {
display: grid;
grid-template-columns: 1fr auto;
row-gap: 8px;
align-items: center;
width: 240px;
font-family: inherit;
}
.progress-with-value-text-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
.progress-with-value-text-value {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
text-align: right;
}
.progress-with-value-text-track {
grid-column: 1 / -1;
height: 8px;
border-radius: 9999px;
background: light-dark(#e2e8f0, #ffffff1f);
overflow: hidden;
}
.progress-with-value-text-indicator {
height: 100%;
/* Percentage of the Root value, set by the library */
width: var(--leve-progress-percent);
border-radius: 9999px;
background: #009dfd;
transition: width 200ms ease;
}
@media (prefers-reduced-motion: reduce) {
.progress-with-value-text-indicator {
transition: none;
}
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| value | null | number | null The current value. |
| min | 0 | number The minimum value. |
| max | 100 | number The maximum value. |
| valueText | – | string A human-readable text for the value (e.g. |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-progress | Always present |
data-state | "indeterminate" | "loading" | "complete" |
data-value | The value, clamped between min and max. Absent when indeterminate |
data-min | The min value |
data-max | The 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 attribute | Value |
|---|---|
data-leve-progress-label | Always present |
data-state | "indeterminate" | "loading" | "complete" |
data-value | The clamped value. Absent when indeterminate |
data-min | The min value |
data-max | The 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 attribute | Value |
|---|---|
data-leve-progress-value-text | Always present |
data-state | "indeterminate" | "loading" | "complete" |
data-value | The clamped value. Absent when indeterminate |
data-min | The min value |
data-max | The 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 attribute | Value |
|---|---|
data-leve-progress-track | Always present |
data-state | "indeterminate" | "loading" | "complete" |
data-value | The clamped value. Absent when indeterminate |
data-min | The min value |
data-max | The max value |
Indicator#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-progress-indicator | Always present |
data-state | "indeterminate" | "loading" | "complete" |
data-value | The clamped value. Absent when indeterminate |
data-min | The min value |
data-max | The max value |
| CSS variable | Value |
|---|---|
--leve-progress-percent | The 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.Rootrendersrole="progressbar"witharia-valueminandaria-valuemax,aria-valuenowunless indeterminate, andaria-valuetextwhenvalueTextis set.- The Root is named by
Progress.Labelthrougharia-labelledby. If you passaria-labeloraria-labelledbyto 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.