CircularProgress

Refer to the v3 ProgressCircle documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Looking for the Progress (linear) migration? See the Progress migration guide.

Component Rename

CircularProgress has been renamed to ProgressCircle in v3.

Structure Changes

In v2, CircularProgress was a single component configured with props:

import { CircularProgress } from "@heroui/react";

export default function App() {
  return (
    <CircularProgress label="Loading..." value={60} />
  );
}

In v3, ProgressCircle uses a compound component pattern:

import { ProgressCircle } from "@heroui/react";

export default function App() {
  return (
    <ProgressCircle aria-label="Loading" value={60}>
      <ProgressCircle.Track>
        <ProgressCircle.TrackCircle />
        <ProgressCircle.FillCircle />
      </ProgressCircle.Track>
    </ProgressCircle>
  );
}

v2: Single CircularProgress component with internal SVG rendering v3: Compound components: ProgressCircle, ProgressCircle.Track (SVG element), ProgressCircle.TrackCircle (background circle), ProgressCircle.FillCircle (progress arc)

2. Colors

v2: default, primary, secondary, success, warning, danger v3: default, accent, success, warning, danger

3. Prop Changes

v2 Prop	v3 Equivalent	Notes
`value`	`value`	Same
`minValue`	`minValue`	Same
`maxValue`	`maxValue`	Same
`isIndeterminate`	`isIndeterminate`	Default changed: `true` in v2 → `false` in v3
`formatOptions`	`formatOptions`	Same
`size`	`size`	Same (`sm`, `md`, `lg`)
`color`	`color`	`primary` → `accent`, `secondary` removed
`label`	-	Use `Label` component
`valueLabel`	-	Use render prop pattern
`showValueLabel`	-	Place value content inside `ProgressCircle`
`strokeWidth`	-	Set `strokeWidth` directly on `ProgressCircle.TrackCircle` and `ProgressCircle.FillCircle`
`isDisabled`	-	Removed
`disableAnimation`	-	Removed
`classNames`	-	Use `className` on individual compound components

Migration Examples

Basic CircularProgress

import { CircularProgress } from "@heroui/react";

<CircularProgress aria-label="Loading..." value={60} />

import { ProgressCircle } from "@heroui/react";

<ProgressCircle aria-label="Loading..." value={60}>
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle />
    <ProgressCircle.FillCircle />
  </ProgressCircle.Track>
</ProgressCircle>

Indeterminate

<CircularProgress aria-label="Loading..." />
{/* isIndeterminate defaults to true in v2 */}

<ProgressCircle isIndeterminate aria-label="Loading...">
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle />
    <ProgressCircle.FillCircle />
  </ProgressCircle.Track>
</ProgressCircle>
{/* isIndeterminate defaults to false in v3, must be explicit */}

With Label

<CircularProgress
  label="Loading..."
  value={70}
  showValueLabel
  size="lg"
/>

import { ProgressCircle, Label } from "@heroui/react";

<div className="flex flex-col items-center gap-2">
  <ProgressCircle aria-label="Loading" value={70} size="lg">
    <ProgressCircle.Track>
      <ProgressCircle.TrackCircle />
      <ProgressCircle.FillCircle />
    </ProgressCircle.Track>
  </ProgressCircle>
  <Label>Loading...</Label>
</div>

Custom SVG Props

<CircularProgress
  value={60}
  strokeWidth={6}
  aria-label="Loading"
/>

<ProgressCircle aria-label="Loading" value={60}>
  <ProgressCircle.Track>
    <ProgressCircle.TrackCircle strokeWidth={6} />
    <ProgressCircle.FillCircle strokeWidth={6} />
  </ProgressCircle.Track>
</ProgressCircle>

Styling Changes

v2: `classNames` Prop

<CircularProgress
  classNames={{
    base: "custom-base",
    svg: "custom-svg",
    track: "custom-track",
    indicator: "custom-fill",
    label: "custom-label",
    value: "custom-value",
  }}
/>

v3: Direct `className` Props

<ProgressCircle className="custom-base" value={60}>
  <ProgressCircle.Track className="custom-svg">
    <ProgressCircle.TrackCircle className="custom-track" />
    <ProgressCircle.FillCircle className="custom-fill" />
  </ProgressCircle.Track>
</ProgressCircle>

Component Anatomy

ProgressCircle (Root)
  └── ProgressCircle.Track (SVG element)
      ├── ProgressCircle.TrackCircle (background circle)
      └── ProgressCircle.FillCircle (progress arc)

Summary

Renamed: CircularProgress → ProgressCircle
Component Structure: Single component → compound components (ProgressCircle.Track, ProgressCircle.TrackCircle, ProgressCircle.FillCircle)
Indeterminate Default Changed: isIndeterminate defaults to false in v3 (was true in v2)
Label: label prop → Label component
SVG Props: strokeWidth on root → set directly on TrackCircle and FillCircle
Color Changes: primary → accent, secondary removed
Removed Props: isDisabled, disableAnimation → use Tailwind CSS
ClassNames Removed: Use className on individual compound components