Circular Progress

A circular progress indicator that displays completion progress in a ring format with support for indeterminate states.

Radix UI Base UI

Installation

pnpm dlx shadcn@latest add @diceui/circular-progress

Layout

Import the parts and compose them together.

import {
  CircularProgress,
  CircularProgressIndicator,
  CircularProgressTrack,
  CircularProgressRange,
  CircularProgressValueText,
} from "@/components/ui/circular-progress";
 
return (
  <CircularProgress>
    <CircularProgressIndicator>
      <CircularProgressTrack />
      <CircularProgressRange />
    </CircularProgressIndicator>
    <CircularProgressValueText />
  </CircularProgress>
)

Or use the Combined component to get all the parts in one.

import { CircularProgressCombined } from "@/components/ui/circular-progress";
 
<CircularProgressCombined />

Examples

Interactive Demo

A circular progress with interactive controls and simulated upload progress.

Colors

Different color themes using Tailwind CSS stroke and text utilities to customize the track, range, and value text colors.

Theming

The circular progress component uses CSS currentColor for stroke colors, making it easy to theme using Tailwind's text or stroke utilities:

Track Theming

<CircularProgressTrack className="text-green-200 dark:text-green-900" />

Range Theming

<CircularProgressRange className="text-green-500" />

Value Text Theming

<CircularProgressValueText className="text-green-700 dark:text-green-300" />

Custom Stroke Styles

You can also use Tailwind's stroke utilities directly:

<CircularProgressTrack className="stroke-blue-200" />
<CircularProgressRange className="stroke-blue-500" />

API Reference

CircularProgress

The main container component for the circular progress.

Prop

Type

Data Attribute	Value
`[data-state]`	`"indeterminate" \| "loading" \| "complete"`
`[data-value]`	The current progress value (only present when not indeterminate).
`[data-max]`	The maximum progress value.
`[data-min]`	The minimum progress value.
`[data-percentage]`	The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).

CircularProgressIndicator

The SVG container that holds the circular progress tracks and ranges.

Prop

Type

Data Attribute	Value
`[data-state]`	`"indeterminate" \| "loading" \| "complete"`
`[data-value]`	The current progress value (only present when not indeterminate).
`[data-max]`	The maximum progress value.
`[data-min]`	The minimum progress value.
`[data-percentage]`	The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).

CircularProgressTrack

The background circle that represents the full range of possible values.

Prop

Type

Data Attribute	Value
`[data-state]`	`"indeterminate" \| "loading" \| "complete"`

CircularProgressRange

The portion of the circle that represents the current progress value.

Prop

Type

Data Attribute	Value
`[data-state]`	`"indeterminate" \| "loading" \| "complete"`
`[data-value]`	The current progress value (only present when not indeterminate).
`[data-max]`	The maximum progress value.
`[data-min]`	The minimum progress value.

CircularProgressValueText

The text element that displays the current progress value or custom content.

Prop

Type

Data Attribute	Value
`[data-state]`	`"indeterminate" \| "loading" \| "complete"`

CircularProgressCombined

The combined component that includes all the parts.

Prop

Type

Accessibility

Uses the progressbar role for proper screen reader identification
Provides aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext attributes
Supports indeterminate state by omitting aria-valuenow when value is null

Notes

The component automatically handles indeterminate states when value is null or undefined
Progress values are automatically clamped to the valid range between min and max
Invalid max or value props will log console errors and use fallback values
The indeterminate animation uses CSS custom properties and can be customized via the --animate-spin-around variable
All stroke colors use currentColor by default, making them responsive to text color changes