Progress

Description

Progress is a non-interactive indicator that visualizes how far a task with a known total has advanced. It renders a <div> with role="progressbar" and comes in two display types: a horizontal line bar and a compact circle ring.

Reach for it when you can measure completion against a total: a file upload at 60%, a multi-step form on step 3 of 5, a download bar, or a dashboard stat ring. Drive it with value (and max when the total is not 100). The line type stretches to fill its container, so give it a width-constrained parent.

Don't use Progress when the duration is unknown or the work is not measurable. For indeterminate "something is happening" feedback, use Spinner. For a passive status or count that doesn't track completion, use Badge or Status Badge.

Installation

pnpm dlx @create-ui/cli add progress

Usage

import { Progress } from "@/components/ui/progress"

<Progress value={60} />

Examples

Type

type switches between the two layouts. line (default) is a horizontal bar that fills its container width; circle is a fixed-size ring for compact spots like cards and stat tiles.

Variants

variant sets the semantic color. Twelve options cover the product intent (primary), status tones (info, success, warning, danger, away), neutral grays (neutral, neutral-static, neutral-soft), and inverse tones for dark surfaces (inverse, inverse-static, inverse-soft).

Appearance

appearance controls the indicator fill. solid (default) is a flat color; gradient fades from a lighter shade into the variant color across the filled portion.

Sizes

size scales the bar thickness and the ring diameter. Four steps (xs, sm, md, lg) with md as the default.

Shape

shape rounds the ends. pill (default) gives fully rounded caps; sharp keeps square corners for a more technical look.

Value and max

value is the current amount and max is the total (default 100). Pass a custom max to track non-percentage totals, such as value={3} max={5} for a 5-step flow. Values are clamped to the 0 to max range.

Accessibility

Progress is a passive indicator. It is not focusable and has no keyboard interactions to document.

ARIA notes:

• The root sets role="progressbar" and manages aria-valuemin, aria-valuemax, and aria-valuenow from value and max automatically.
• Add an aria-label (or aria-labelledby pointing at a visible label) so assistive tech can announce what the bar is measuring, since the value alone has no context.
• There is no built-in text output of the percentage. If users need the numeric value, render it next to the component yourself.

Styling

Tailwind override: pass className to merge Tailwind classes with the component's classes (via cn()):

<Progress className="h-1" value={60} />

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="progress" on the root element.
• data-slot="progress-indicator" on the line fill and the circle's arc.
• data-slot="progress-track" on the circle's background ring (circle type only).
• data-type="<type>", data-variant="<variant>", data-appearance="<appearance>", data-size="<size>", data-shape="<shape>" on the root.

Target a specific state in CSS:

[data-slot="progress"][data-variant="success"] {
  /* … */
}

Related Components

• Spinner: use this for indeterminate loading when the duration or total is unknown.
• Badge: passive label for a status or count that doesn't track completion.
• Status Badge: colored dot + label for presence states (online, offline, away).

API Reference

Progress

Determinate progress indicator rendered as a <div role="progressbar">. Extends React.ComponentProps<"div"> (minus its own typed props and children), so standard div attributes (id, aria-label, style, etc.) are passed through to the root.

Props

Variants