1. Components
  2. Feedback
  3. Progress

Progress

Progress shows the completion progress of a task in shape of a bar, displayed as a progress bar..

Aria docsAria API ReferenceReport an issueEdit this page
<Progress value={75} />

Installation

npx dotui-cli@latest add progress

Usage

Use Progress to show the completion progress of a task. It can represent either determinate or indeterminate progress.

Best pratices

When possible, use a determinate progress indicator.
An indeterminate progress indicator shows that a process is occurring, but it doesn't help people estimate how long a task will take.
A determinate progress indicator can help people decide whether to do something else while waiting for the task to complete, restart the task at a different time, or abandon the task.

Options

Variant

Use the variant prop to control the visual style of the Progress. The default variant is "default".

default
success
accent
danger
warning
<Progress variant="default" />
<Progress variant="success" />
<Progress variant="accent" />
<Progress variant="danger" />
<Progress variant="warning" />

Size

Use the size prop to control the size of the Progress. The default variant is "md".

sm
md
lg
<Progress size="sm" />
<Progress size="md" />
<Progress size="lg" />

Label

A visual label can be provided for the Progress using the label prop, or a hidden label using aria-label prop.

Loading...
<Progress aria-label="loading" />
<Progress label="loading..." />

Value label

Set the showValueLabel prop to true to display the current value of the progress bar.

Loading75%
<Progress label="Loading" showValueLabel value={75} />

Format options

Values are formatted as a percentage by default, but this can be modified by using the formatOptions prop to specify a different format.

Sending…¥60
<Progress
  label="Sending…"
  showValueLabel
  formatOptions={{ style: "currency", currency: "JPY" }}
  value={60}
/>

Custom value label

The valueLabel prop allows the formatted value to be replaced with a custom string.

Feeding…30 of 100 dogs
<Progress
  label="Feeding…"
  showValueLabel
  valueLabel="30 of 100 dogs"
  value={30}
/>

Indeterminate

The isIndeterminate prop can be used to represent an interdeterminate operation.

<Progress isIndeterminate aria-label="Loading" />

Duration

Use the duration prop to indicate an approximate duration of an indeterminate task. Once the duration times out, the progress bar will start an indeterminate animation.

<Progress duration="30s" />

Min and max values

A custom value scale can be used by setting the minValue and maxValue props.

<Progress
  aria-label="Min and max values"
  minValue={50}
  maxValue={150}
  value={100}
/>

Examples

Composition

If you need to customize things further, you can drop down to the composition level.

Progress
50%
<ProgressRoot value={50} className="flex-row items-center gap-4">
  <Label>Progress</Label>
  <ProgressIndicator />
  <ProgressValueLabel />
</ProgressRoot>

Custom color

<Progress
  value={75}
  aria-label="Custom color"
  classNames={{
    indicator: "bg-slate-300 dark:bg-slate-800",
    filler: "bg-slate-800 dark:bg-slate-300",
  }}
/>

Toolbar

"use client";

import * as React from "react";
import { Button } from "@/registry/ui/default/core/button";
import { Input, InputRoot } from "@/registry/ui/default/core/input";
import { Progress } from "@/registry/ui/default/core/progress";
import { TextFieldRoot } from "@/registry/ui/default/core/text-field";
import { ALargeSmallIcon, RotateCwIcon } from "@/__icons__";

export default function Demo() {
  const [key, setKey] = React.useState(0);
  const refresh = () => setKey((key) => key + 1);
  return (
    <TextFieldRoot key={key} defaultValue="https://dotui.org" aria-label="URL">
      <InputRoot className="relative h-10 overflow-hidden px-1 pb-0.5">
        <Button
          size="sm"
          variant="quiet"
          shape="square"
          aria-label="translate"
          className="size-7"
        >
          <ALargeSmallIcon />
        </Button>
        <Input className="text-center" />
        <Button
          onPress={refresh}
          size="sm"
          variant="quiet"
          shape="square"
          className="size-7"
          aria-label="Refresh"
        >
          <RotateCwIcon />
        </Button>
        <Progress
          value={50}
          size="sm"
          variant="accent"
          duration="5s"
          aria-label="loading indicator"
          className="absolute bottom-0 left-0 right-0"
        />
      </InputRoot>
    </TextFieldRoot>
  );
}

API Reference

PropTypeDefaultDescription
variant
"default" | "primary" | "danger" | "success" | "warning"
"default"
The visual style of the progress indicator.
size
"sm" | "md" | "lg"
"md"
The size of the progress indicator
isIndeterminate
boolean
-
Whether presentation is indeterminate when progress isn't known.
formatOptions
Intl.NumberFormatOptions
{style: 'percent'}
The display format of the value label.
valueLabel
ReactNode
-
The content to display as the value's label (e.g. 1 of 4).
showValueLabel
boolean
false
Whether the value's label is displayed.
value
number
0
The current value (controlled).
minValue
number
0
The smallest value allowed for the input.
maxValue
number
100
The largest value allowed for the input.
children
ReactNode | (values: ProgressBarRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode
-
The children of the component. A function may be provided to alter the children based on component state.
className
string
-
The CSS className for the element.
style
CSSProperties | (values: ProgressBarRenderProps & {defaultStyle: CSSProperties}) => CSSProperties
-
The inline style for the element. A function may be provided to compute the style based on component state.
CSS SelectorDescription
[aria-valuetext]
A formatted version of the value.
:not([aria-valuenow])
Whether the progress bar is indeterminate.

Last updated on 10/11/2024

AlertSkeleton