Progress

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

Looking for the CircularProgress migration? See the CircularProgress migration guide.

Component Rename

Progress has been renamed to ProgressBar in v3.

Structure Changes

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

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

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

In v3, ProgressBar uses a compound component pattern:

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

export default function App() {
  return (
    <ProgressBar value={60}>
      <Label>Loading...</Label>
      <ProgressBar.Output />
      <ProgressBar.Track>
        <ProgressBar.Fill />
      </ProgressBar.Track>
    </ProgressBar>
  );
}

Key Changes

1. Component Structure

v2: Single Progress component with all parts rendered internally v3: Compound components: ProgressBar, ProgressBar.Output, ProgressBar.Track, ProgressBar.Fill, plus external Label

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`	Same
`formatOptions`	`formatOptions`	Same
`size`	`size`	Same (`sm`, `md`, `lg`)
`color`	`color`	`primary` → `accent`, `secondary` removed
`label`	-	Use `Label` component
`valueLabel`	`valueLabel`	Same
`showValueLabel`	-	Include or omit `ProgressBar.Output`
`radius`	-	Removed (use Tailwind CSS)
`isStriped`	-	Removed (use Tailwind CSS on `ProgressBar.Fill`)
`isDisabled`	-	Removed
`disableAnimation`	-	Removed
`classNames`	-	Use `className` on individual compound components

Migration Examples

Basic Progress

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

<Progress label="Loading..." value={60} color="primary" />

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

<ProgressBar value={60} color="accent">
  <Label>Loading...</Label>
  <ProgressBar.Output />
  <ProgressBar.Track>
    <ProgressBar.Fill />
  </ProgressBar.Track>
</ProgressBar>

Indeterminate

<Progress isIndeterminate aria-label="Loading..." size="sm" />

<ProgressBar isIndeterminate aria-label="Loading..." size="sm">
  <ProgressBar.Track>
    <ProgressBar.Fill />
  </ProgressBar.Track>
</ProgressBar>

Without Label (Accessibility)

<Progress aria-label="Loading..." value={70} />

<ProgressBar aria-label="Loading..." value={70}>
  <ProgressBar.Track>
    <ProgressBar.Fill />
  </ProgressBar.Track>
</ProgressBar>

Custom Formatting

<Progress
  label="Budget"
  formatOptions={{ style: "currency", currency: "USD" }}
  maxValue={10000}
  value={4000}
/>

<ProgressBar
  formatOptions={{ style: "currency", currency: "USD" }}
  maxValue={10000}
  value={4000}
>
  <Label>Budget</Label>
  <ProgressBar.Output />
  <ProgressBar.Track>
    <ProgressBar.Fill />
  </ProgressBar.Track>
</ProgressBar>

Styling Changes

v2: `classNames` Prop

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

v3: Direct `className` Props

<ProgressBar className="custom-base" value={60}>
  <Label className="custom-label">Loading</Label>
  <ProgressBar.Output className="custom-value" />
  <ProgressBar.Track className="custom-track">
    <ProgressBar.Fill className="custom-fill" />
  </ProgressBar.Track>
</ProgressBar>

Component Anatomy

ProgressBar (Root)
  ├── Label (optional)
  ├── ProgressBar.Output (optional, formatted value display)
  └── ProgressBar.Track
      └── ProgressBar.Fill

Summary

Renamed: Progress → ProgressBar
Component Structure: Single component → compound components (ProgressBar.Output, ProgressBar.Track, ProgressBar.Fill)
Label: label prop → Label component
Value Display: showValueLabel prop → include or omit ProgressBar.Output
Color Changes: primary → accent, secondary removed
Removed Props: radius, isStriped, isDisabled, disableAnimation → use Tailwind CSS
ClassNames Removed: Use className on individual compound components

On this page