CircularProgress

Migration guide for CircularProgress from HeroUI v2 to v3 (now ProgressCircle)

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:

1import { CircularProgress } from "@lenso/ui";2
3export default function App() {4  return (5    <CircularProgress label="Loading..." value={60} />6  );7}

In v3, ProgressCircle uses a compound component pattern:

1import { ProgressCircle } from "@lenso/ui";2
3export default function App() {4  return (5    <ProgressCircle aria-label="Loading" value={60}>6      <ProgressCircle.Track>7        <ProgressCircle.TrackCircle />8        <ProgressCircle.FillCircle />9      </ProgressCircle.Track>10    </ProgressCircle>11  );12}

Key Changes

1. Component Structure

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

1import { CircularProgress } from "@lenso/ui";2
3<CircularProgress aria-label="Loading..." value={60} />

Indeterminate

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

With Label

1<CircularProgress2  label="Loading..."3  value={70}4  showValueLabel5  size="lg"6/>

Custom SVG Props

1<CircularProgress2  value={60}3  strokeWidth={6}4  aria-label="Loading"5/>

Styling Changes

v2: `classNames` Prop

1<CircularProgress2  classNames={{3    base: "custom-base",4    svg: "custom-svg",5    track: "custom-track",6    indicator: "custom-fill",7    label: "custom-label",8    value: "custom-value",9  }}10/>

v3: Direct `className` Props

1<ProgressCircle className="custom-base" value={60}>2  <ProgressCircle.Track className="custom-svg">3    <ProgressCircle.TrackCircle className="custom-track" />4    <ProgressCircle.FillCircle className="custom-fill" />5  </ProgressCircle.Track>6</ProgressCircle>

Component Anatomy

1ProgressCircle (Root)2  └── ProgressCircle.Track (SVG element)3      ├── ProgressCircle.TrackCircle (background circle)4      └── 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