║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: Circular Progress description: A circular progress indicator that displays completion progress in a ring format with support for indeterminate states. preview: true links: api: /docs/components/circular-progress#api-reference

<ComponentTabs name="circular-progress-demo" />

Installation

CLI

npx shadcn@latest add "https://diceui.com/r/circular-progress"

Manual

<Steps> <Step> Install the following dependencies:

 ```package-install
 @radix-ui/react-slot
 ```

</Step> <Step> Copy and paste the following code into your project.

<ComponentSource name="circular-progress" />

</Step> <Step> Add the following CSS animations to your `globals.css` file:

```css
@theme {
  --animate-spin-around: spin-around 0.8s linear infinite;

  @keyframes spin-around {
    0% {
      transform: rotate(-90deg);
    }
    100% {
      transform: rotate(270deg);
    }
  }
}
```

</Step> </Steps>

Layout

Import the parts and compose them together.

import * as CircularProgress from "@/components/ui/circular-progress";

<CircularProgress.Root>
  <CircularProgress.Indicator>
    <CircularProgress.Track />
    <CircularProgress.Range />
  </CircularProgress.Indicator>
  <CircularProgress.ValueText />
</CircularProgress.Root>

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

import { CircularProgressCombined } from "@/registry/default/ui/circular-progress";

<CircularProgressCombined />

Examples

Interactive Demo

A circular progress with interactive controls and simulated upload progress.

<ComponentTabs name="circular-progress-interactive-demo" />

Themes

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

<ComponentTabs name="circular-progress-themes-demo" />

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

Root

The main container component for the circular progress.

<AutoTypeTable path="./types/docs/circular-progress.ts" name="RootProps" />

<DataAttributesTable attributes={[ { title: "[data-state]", value: ["indeterminate", "loading", "complete"], }, { title: "[data-value]", value: "The current progress value (only present when not indeterminate).", }, { title: "[data-max]", value: "The maximum progress value.", }, { title: "[data-min]", value: "The minimum progress value.", }, { title: "[data-percentage]", value: "The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).", }, ]} />

Indicator

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

<AutoTypeTable path="./types/docs/circular-progress.ts" name="IndicatorProps" />

<DataAttributesTable attributes={[ { title: "[data-state]", value: ["indeterminate", "loading", "complete"], }, { title: "[data-value]", value: "The current progress value (only present when not indeterminate).", }, { title: "[data-max]", value: "The maximum progress value.", }, { title: "[data-min]", value: "The minimum progress value.", }, { title: "[data-percentage]", value: "The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).", }, ]} />

Track

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

<AutoTypeTable path="./types/docs/circular-progress.ts" name="TrackProps" />

<DataAttributesTable attributes={[ { title: "[data-state]", value: ["indeterminate", "loading", "complete"], }, ]} />

Range

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

<AutoTypeTable path="./types/docs/circular-progress.ts" name="RangeProps" />

<DataAttributesTable attributes={[ { title: "[data-state]", value: ["indeterminate", "loading", "complete"], }, { title: "[data-value]", value: "The current progress value (only present when not indeterminate).", }, { title: "[data-max]", value: "The maximum progress value.", }, { title: "[data-min]", value: "The minimum progress value.", }, ]} />

ValueText

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

<AutoTypeTable path="./types/docs/circular-progress.ts" name="ValueTextProps" />

<DataAttributesTable attributes={[ { title: "[data-state]", value: ["indeterminate", "loading", "complete"], }, ]} />

Combined

The combined component that includes all the parts.

<AutoTypeTable path="./types/docs/circular-progress.ts" name="RootProps" />

Accessibility

Screen Reader Support

• 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

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║