Full Migration

Step 1: Update Dependencies

Update React

v3 requires React 19+. Update your React version:

npm install react@^19.0.0 react-dom@^19.0.0

pnpm add react@^19.0.0 react-dom@^19.0.0

yarn add react@^19.0.0 react-dom@^19.0.0

bun add react@^19.0.0 react-dom@^19.0.0

Note: These dependency updates can be done before switching HeroUI (won't break project). However, the HeroUI package switch should only happen AFTER all component code is migrated.

Update HeroUI Packages

Important: Do this AFTER migrating all component code. Remove v2 packages and install v3:

npm uninstall @heroui/react @heroui/theme
npm install @heroui/styles @heroui/react

pnpm remove @heroui/react @heroui/theme
pnpm add @heroui/styles @heroui/react

yarn remove @heroui/react @heroui/theme
yarn add @heroui/styles @heroui/react

bun remove @heroui/react @heroui/theme
bun add @heroui/styles @heroui/react

Remove Framer Motion

v3 no longer requires Framer Motion:

npm uninstall framer-motion

pnpm remove framer-motion

yarn remove framer-motion

bun remove framer-motion

Update Tailwind CSS

Ensure you're using Tailwind CSS v4:

npm install tailwindcss@^4.0.0

pnpm add tailwindcss@^4.0.0

yarn add tailwindcss@^4.0.0

bun add tailwindcss@^4.0.0

Step 2: Update Theming Configuration

Remove Tailwind Plugin Configuration

v2 Configuration:

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  plugins: [heroui()],
  // ... other config
};

v3 Configuration:

Remove the heroui() plugin from your Tailwind config. If you only used Tailwind for HeroUI and have no other customizations, you can remove tailwind.config.js entirely. Otherwise, keep the file but remove the HeroUI plugin configuration.

Update CSS Imports

v2 CSS:

/* globals.css or main.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

v3 CSS:

/* globals.css or main.css */
@import "tailwindcss";
@import "@heroui/styles"; 

Remove Theme Plugin File

If you created a hero.ts file for v2, you can remove it:

rm hero.ts

Step 3: Remove HeroUIProvider

v3 does not require a Provider component. Remove it from your application root.

v2 Code:

// app.tsx or App.tsx
import {HeroUIProvider} from "@heroui/react";

function App() {
  return (
    <HeroUIProvider>
      <YourApplication />
    </HeroUIProvider>
  );
}

v3 Code:

// app.tsx or App.tsx
function App() {
  return <YourApplication />;
}

If you were using Provider props:

If you were using Provider props like navigate, useHref, locale, disableAnimation, etc., you'll need to handle these differently:

• Router integration: Use React Router or your routing library directly
• Locale: Use React Aria's I18nProvider directly if needed
• Animation: See the Animation Changes section below

Animation Changes

v3 removes the Framer Motion dependency and handles animations differently:

• CSS-based animations: v3 uses native CSS animations and transitions instead of JavaScript-based animations
• Better performance: CSS animations provide better performance and smoother animations
• No global disable: Unlike v2's Provider disableAnimation prop, there's no global animation toggle in v3
• Per-component control: Control animations through CSS or component-specific props where available
• Custom animations: Use standard CSS @keyframes and transition properties for custom animations

Step 4: Replace Removed Hooks

HeroUI v2 provided component hooks (like useSwitch, useInput, useCheckbox, etc.) and utility hooks like useDisclosure. HeroUI v3 removes most component hooks in favor of compound components, and replaces useDisclosure with useOverlayState.

See the comprehensive Hooks Migration Guide for:

• Component hooks removal and migration to compound components
• useDisclosure → useOverlayState migration
• Migration strategies and examples

Step 5: Update Component Imports

All components are now imported from a single package:

v2 Imports:

// Individual packages (if used)
import {Button} from "@heroui/button";
import {Card} from "@heroui/card";

// Or from main package
import {Button, Card} from "@heroui/react";

v3 Imports:

// All components from single package
import {Button, Card} from "@heroui/react";

TypeScript Considerations

If you're using TypeScript, be aware of type changes in v3:

// Import types alongside components
import {Button, type ButtonProps} from "@heroui/react";

// Compound component types are properly exported
import {Checkbox, type CheckboxProps} from "@heroui/react";

// Type names may have changed - check component documentation
type MyButtonProps = ButtonProps & {
  customProp?: string;
};

Common type changes:

• Component prop interfaces may have different names or properties
• Compound component parts have their own type exports
• Ref types updated to match React 19 patterns

Step 6: Component Migration

Use the Component Migration Reference table to find migration guides for each component. Migrate components according to their specific guides.

Key points:

• Review individual component migration guides as needed
• Migrate component APIs, props, and structure
• Update compound component patterns (Checkbox, Radio, Switch, Card, Modal, etc.)
• Update group components (ButtonGroup, CheckboxGroup, RadioGroup)
• Handle removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User) - replace with HTML elements
• Handle in-progress/planned components - replace with HTML elements until v3 components are available

Step 7: Update Custom Theme Overrides

If you had custom theme overrides in v2, you'll need to update them for v3's CSS-based theming system.

v2 Theme Customization:

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          colors: {
            primary: {
              // custom colors
            },
          },
        },
      },
    }),
  ],
};

v3 Theme Customization:

v3 uses CSS variables. Override them in your CSS:

/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";

:root {
  --color-primary: /* your color */;
  /* other CSS variables */
}

Check the Theming documentation for available CSS variables.

This is a good point to pause and verify component functionality before proceeding to styling migration.

Step 8: Hooks Migration

After component migration is complete, ensure all hooks have been migrated:

1. Replace component hooks: Replace hooks like useSwitch, useInput, useCheckbox, etc. with compound components
2. Migrate useDisclosure: Replace useDisclosure with useOverlayState for overlay state management
3. Reference hooks guide: See the Hooks Migration Guide for detailed migration instructions and examples

Step 9: Styling Migration

After hooks migration is complete, proceed with styling changes. This is a separate step to ensure component functionality is verified before addressing visual changes.

Styling Migration Guide:

See the comprehensive Styling Migration Guide for:

• Utility class changes (text-tiny → text-xs, rounded-small → rounded-sm, etc.)
• Color token updates (bg-primary → bg-accent, bg-content1 → bg-surface, etc.)
• Component styling differences (sizes, spacing, border radius)
• CSS variable changes
• Visual differences and alignment changes

Key Styling Changes:

• Utility Classes: Custom utilities replaced with standard Tailwind classes
• Color Tokens: primary → accent, secondary removed, content1-4 → surface/overlay
• Numbered Scales: Color scales like primary-50, primary-100 removed
• Border Radius: Default values changed (smaller in v3)
• Component Styles: Updated default sizes, padding, and spacing

Migration Checklist:

• Review Styling Migration Guide
• Update utility classes (text-tiny → text-xs, etc.)
• Update color tokens (bg-primary → bg-accent, etc.)
• Update content colors (bg-content1 → bg-surface or bg-overlay)
• Update numbered color scales (bg-primary-50 → bg-accent-soft)
• Review component styling changes (sizes, spacing, border radius)
• Test visual appearance and adjust as needed

Step 10: Testing

After migration, thoroughly test your application:

1. Visual Testing: Check all components render correctly
2. Functionality: Test all interactions and behaviors
3. Accessibility: Verify keyboard navigation and screen reader support
4. Responsive Design: Test on different screen sizes
5. Performance: Check bundle size and runtime performance