Skip to main content

Progress

Show measurable or indeterminate task progress.

Uploading design.fig65%
Props
Slots

Anatomy#

Progress [component; slot=root]
├── label [slot]
├── value [slot]
└── track [slot]
    └── indicator [slot]

Usage#

Use Progress for measurable task completion or for work whose end is not yet known. Choose a determinate value only when it represents real progress. For a loading placeholder of content structure, use Skeleton.

import { Progress } from 'moraine'

export function Example() {
  return <Progress value={40} max={100} aria-label="Upload progress" />
}

Progress models#

Pass a numeric value from 0 to max for determinate progress; max defaults to 100, and a value outside the range is clamped. Omit value for indeterminate progress, which sets no aria-valuenow and takes its aria-valuetext from the progress.indeterminate message. Use animation (carousel, reverse, swing, or elastic) to change the indeterminate motion.

<Progress value={65} aria-label="Uploading design.fig" />
<Progress aria-label="Scanning for malware" />

Label and value#

Supply aria-label or a labelling relationship when the surrounding context does not name the operation. label fills the label slot, and a string label is also the default aria-label. An explicit aria-label takes precedence. valueLabel shows the percentage in the value slot; pass a formatter to customize both the displayed text and aria-valuetext. Without valueLabel, aria-valuetext is still the formatted percentage. Indeterminate progress keeps the label and hides the value.

<Progress value={82} label="Downloading installation bundle" valueLabel aria-label="Download" />
<Progress value={40} valueLabel={({ percent }) => `${percent}% complete`} aria-label="Export" />

Orientation#

Progress fills left to right by default. Set orientation="vertical" for a bar that fills from the bottom, for example a battery or level meter. The vertical bar grows to its container height with a minimum of 9rem.

<Progress value={72} orientation="vertical" aria-label="Battery level" />

Number format#

formatOptions accepts Intl.NumberFormat options and formats the displayed value and aria-valuetext with the provider locale. A percent style formats the completed fraction; other styles format value. Without formatOptions, the text is the percentage rounded to two decimals. A valueLabel formatter takes precedence.

<Progress value={3} max={4} valueLabel formatOptions={{ style: 'percent' }} aria-label="Setup" />
<Progress value={42} valueLabel formatOptions={{ style: 'unit', unit: 'megabyte' }} aria-label="Upload" />

Examples#

Upload a file or wait on a scan#

Use a determinate value for known bytes. Omit value while a scanner has no trustworthy percentage.

import { Progress } from 'moraine'

export function Models() {
  return (
    <div class="max-w-md w-full space-y-4">
      <Progress label="Uploading design.fig" value={65} aria-label="Uploading design.fig" />
      <Progress label="Scanning for malware" aria-label="Scanning for malware" />
    </div>
  )
}

Announce a bundle download#

Set label and valueLabel when the operation name and percentage should appear with the bar. Keep aria-label as the accessible name.

import { Progress } from 'moraine'

export function Semantics() {
  return (
    <div class="max-w-md w-full">
      <Progress
        label="Downloading installation bundle"
        value={82}
        valueLabel
        aria-label="Downloading installation bundle"
      />
    </div>
  )
}

Show horizontal and vertical meters#

Use orientation="vertical" for level meters that fill from the bottom.

import { Progress } from 'moraine'

export function Orientation() {
  return (
    <div class="flex gap-8 items-end">
      <div class="max-w-md w-full">
        <Progress
          label="Disk usage"
          value={72}
          valueLabel
          orientation="horizontal"
          aria-label="Disk usage"
        />
      </div>
      <Progress value={72} orientation="vertical" aria-label="Battery level" />
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-indeterminate
Slot: progressprogress-indicator
Description: Present when the checkbox or progress state is indeterminate.
data-progress
Slot: progressprogress-indicator
Description: Stores whether determinate progress is loading or complete.

Props#

Renders a <div> element by default.

Prop