Progress

A progress bar shows how far a task has gotten. Use it for uploads, downloads, and exports, and pass value={null} until you can measure the work. For a static reading in a fixed range, use Meter instead.

Preview#

"use client";
 
import * as React from "react";
import {
  ProgressRoot,
  ProgressTrack,

Installation#

npxnpx shadcn@latest add @cubby-ui/progress

Usage#

import {
  ProgressRoot,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/cubby-ui/progress/progress";

<ProgressRoot>
  <ProgressLabel />
  <ProgressValue />
  <ProgressTrack>
    <ProgressIndicator />
  </ProgressTrack>
</ProgressRoot>

Composition#

ProgressRoot
├── ProgressLabel
├── ProgressValue
└── ProgressTrack
    ├── ProgressBuffer
    └── ProgressIndicator

The root puts the label and value on the first row and spans everything else below, so you don't need a wrapper. For a ring, swap the track for ProgressCircle:

ProgressRoot
├── ProgressCircle
│   └── ProgressValue
└── ProgressLabel

Examples#

Sizes#

Use size to set the track thickness.

import {
  ProgressRoot,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,

Variants#

Use variant to color the indicator with the primary, neutral, or a status token.

import {
  ProgressRoot,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,

Indeterminate#

Pass value={null} while the amount of work is unknown, and the indicator sweeps across the track.

import {
  ProgressRoot,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
} from "@/components/ui/cubby-ui/progress/progress";

Upload Lifecycle#

Switch value from null to a number, then variant to "success", to walk a task from connecting to done.

"use client";
 
import * as React from "react";
import { Button } from "@/components/ui/cubby-ui/button";
import {
  ProgressRoot,

Buffer#

Set buffer on the root and place ProgressBuffer before the indicator to show a second value, like loaded media.

"use client";
 
import * as React from "react";
import {
  ProgressRoot,
  ProgressTrack,

Circle#

Use ProgressCircle in place of the track where a bar won't fit; a nested ProgressValue centers and scales with the ring. At value={null} it spins, so a small ring doubles as a spinner.

"use client";
 
import * as React from "react";
import {
  ProgressRoot,
  ProgressCircle,

Attachment List#

Give ProgressCircle a small size to fit a ring inline in a list row.

"use client";
 
import * as React from "react";
import {
  ProgressRoot,
  ProgressCircle,

Custom Range and Format#

Use min, max, and format to count in your own units.

import {
  ProgressRoot,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,

Accessibility#

Screen readers skip ProgressValue and read the root's value text instead. When the visible text adds context, like "1.4 GB of 4.2 GB", pass the same string through getAriaValueText.

With reduced motion on, the indicator jumps between values, and the indeterminate sweep and ring spin turn into a slow fade.

ProgressRoot renders a <div>. To put a ring inside a button, pass render={<span />} to keep the markup valid.

API Reference#

The Progress component is built on top of Base UI's Progress. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Progress documentation.

Props#

ProgressRoot#

Holds the value and lays out the parts. Wraps Base UI's Progress.Root.

ProgressTrack#

The full range of the bar. Wraps Base UI's Progress.Track.

ProgressIndicator#

The filled part of the track. Wraps Base UI's Progress.Indicator.

ProgressBuffer#

The root's buffer, drawn behind the indicator. A plain <div>, hidden while indeterminate.

ProgressCircle#

A ring drawn in place of the track, driven by the same root. A plain <span> holding an SVG.

ProgressValue#

The formatted value text, hidden while indeterminate. Wraps Base UI's Progress.Value.

Data Attributes#

ProgressBuffer and ProgressCircle don't get the state attributes. Style them from the root with group-data-complete/progress: and the like.

CSS Variables#