Progress
How far a task has come, as a bar with its label and value, or as an ongoing task of unknown length.
A progress bar shows how far a task has come: an upload, an import, a batch. With a value it shows
the share done; with value={null} it shows that the task runs without a known end. It is built
on Base UI's progress. For a short wait without a measure, a spinner
is enough; for steps the reader takes, use a stepper.
// apps/docs/examples/ui/progress.tsx'use client';
import {useEffect, useState} from 'react';
import {Button} from '@workspace/active-ui/components/primitives/button';import { Progress, ProgressLabel, ProgressValue,} from '@workspace/active-ui/components/primitives/progress';
/** * How far a task has come: an upload that advances (simulated with a * timer), with its label and its value as text, and a task of unknown * length (`value={null}`). */export default function ProgressExample() { const [value, setValue] = useState(0); const [running, setRunning] = useState(false); useEffect(() => { if (!running) return; const timer = window.setInterval(() => { setValue((current) => { if (current >= 100) { setRunning(false); return 100; } return current + 10; }); }, 300); return () => window.clearInterval(timer); }, [running]); return ( <div className="flex w-full max-w-sm flex-col gap-8"> <div className="flex flex-col gap-3"> <Progress value={value}> <ProgressLabel>Uploading participants.csv</ProgressLabel> <ProgressValue /> </Progress> <Button variant="outline" size="sm" className="self-start" disabled={running} onClick={() => { setValue(0); setRunning(true); }} > {value === 100 ? 'Upload again' : 'Start the upload'} </Button> </div> <Progress value={null}> <ProgressLabel>Checking the addresses</ProgressLabel> </Progress> </div> );}Usage#
import { Progress, ProgressLabel, ProgressValue,} from '@workspace/active-ui/components/primitives/progress';
<Progress value={60}> <ProgressLabel>Uploading participants.csv</ProgressLabel> <ProgressValue /></Progress>;Anatomy#
Progress: the bar and its state.value(a number betweenminandmax, default0to100, ornullfor unknown),formatandlocalefor the value text.ProgressandLabel Progress: the label and the value as text, above the bar. The value is formatted withValue Intl..Number Format ProgressandTrack Progress: the bar itself, whichIndicator Progressrenders.
What your application provides#
The value as the task advances, and a label that says what is in progress.
locale, so the value text follows your presentation rather than the browser's language.What happens when the task ends: replace the bar with the result.
Accessibility#
The bar is a role="progressbar" named by its label, with its value (aria-) and the
value text; without a value it is reported as busy. A screen reader reads the value when it reaches
the bar; announce the end of a long task separately, for example with a toast.
API#
Import from @workspace/
All props come from the Base UI part this component is built on.
Props
- Type
number | null
The current value. The component is indeterminate when value is null.
- Type
string
A string value that provides a user-friendly name for aria-, the current value of the progress bar.
- Type
Intl.Number Format Options
Options to format the value.
- Type
(formattedValue, value) => string
Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.
- Type
Intl.Locales Argument
The locale used by Intl. when formatting the value. Defaults to the user's runtime locale.
- Type
number- Default
100
The maximum value.
- Type
number- Default
0
The minimum value.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Other parts#
ProgressValue
All props come from the Base UI part this component is built on.
Props
- Type
(formattedValue, value) => React Node null
The content of this part, in the forms its type allows.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Parts that take only their element’s attributes
Progress: the attributes of its element, with className and ref, and Base UI'sTrack renderto use your own element.Progress: the attributes of its element, with className and ref, and Base UI'sIndicator renderto use your own element.Progress: the attributes of its element, with className and ref, and Base UI'sLabel renderto use your own element.
This page adapts the Progress documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.