Migration

Overview

Migration Workflow

Step 1: Component Migration

1. Check this guide (index.mdx) for general migration steps
2. Review individual component migration guides as needed (see Component Migration Reference)
3. Migrate component APIs, props, and structure
4. Stop here and wait for user confirmation before proceeding

Step 2: Styling Migration

1. After component migration is complete, check the Styling Migration Guide (styling.mdx)
2. Update utility classes (text-tiny → text-xs, rounded-small → rounded-sm, etc.)
3. Update color tokens (bg-primary → bg-accent, bg-content1 → bg-surface, etc.)
4. Update component styling (sizes, spacing, border radius)
5. Review visual differences and adjust as needed

Why Separate Steps?

• Component migration focuses on API changes, props, and component structure
• Styling migration focuses on CSS classes, color tokens, and visual appearance
• Separating these allows you to verify component functionality before addressing styling changes
• Makes the migration process more manageable and easier to debug

Major Changes

• No Provider Required: v3 removes the need for HeroUIProvider
• CSS-First Theming: New CSS-based theming system replaces Tailwind plugin
• React 19 Required: v3 requires React 19+ (v2 supports React 18+)
• No Framer Motion: Animation library dependency removed
• Component API Updates: Many components use React Aria Components patterns
• Compound Components: New compound component patterns for better customization

Key API Changes

General Props Changes

• key prop → id and textValue props (ListBox, etc.)
• onClick → onPress (all interactive components)

Compound Component Patterns

Many components now use compound component patterns for better composition and flexibility. For example:

• Checkbox: Checkbox, Checkbox.Control, Checkbox.Indicator, Checkbox.Content
• Card: Card, Card.Header, Card.Title, Card.Description, Card.Content, Card.Footer
• Modal: Modal, Modal.Overlay, Modal.Content, Modal.Header, Modal.Footer, Modal.Body
• Select: Select, Select.Trigger, Select.Value, Select.Content, Select.Item
• Dropdown: Dropdown, Dropdown.Trigger, Dropdown.Content, Dropdown.Item

See specific component migration guides for detailed examples and usage patterns.

Migration Steps

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

Update HeroUI Packages

Remove v2 packages and install v3:

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

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

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

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

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: 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
• Event handler types changed from onClick to onPress (uses React Aria types)
• Compound component parts have their own type exports
• Ref types updated to match React 19 patterns

Step 5: Component Migration Reference

Use the table below to quickly find migration guidance for each component. Use the link in the "Migration Guide" column to jump to detailed migration instructions.

New Components in v3

v3 introduces several new components not available in v2:

Step 6: 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 7: Styling Migration

After component 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 (styling.mdx) 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 8: 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

Migration Checklist

Use this checklist to track your migration progress:

Dependencies

• Update React to v19+
• Update HeroUI packages to v3
• Remove Framer Motion
• Update Tailwind CSS to v4

Configuration

• Remove heroui() plugin from Tailwind config
• Update CSS imports
• Remove hero.ts file (if exists)

Application Code - Component Migration

• Remove HeroUIProvider wrapper
• Handle Provider props migration (router, locale, animations)
• Update all component imports to @heroui/react
• Migrate renamed components (Divider → Separator, Autocomplete → Combobox, NumberInput → NumberField)
• Update compound component patterns (Checkbox, Radio, Switch, Card, Modal, etc.)
• Update group components (CheckboxGroup, RadioGroup, SwitchGroup)
• Change onClick to onPress for interactive components
• Update key prop to id and textValue where applicable
• Update TypeScript type references (if using component types)
• Handle removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User)
• Plan alternatives for in-progress/planned components (Badge, Calendar, DatePicker, Drawer, Pagination, Progress, ScrollShadow, Table, Toast)
• Consider using asChild prop for flexible composition
• Verify component functionality before proceeding to styling migration

Application Code - Styling Migration

• Review Styling Migration Guide (styling.mdx)
• Update utility classes (text-tiny → text-xs, rounded-small → rounded-sm, etc.)
• Update color tokens (bg-primary → bg-accent, bg-secondary → bg-default, etc.)
• Update content colors (bg-content1 → bg-surface or bg-overlay)
• Update numbered color scales (bg-primary-50 → bg-accent-soft, etc.)
• Update transition utilities (.transition-background → transition-colors, etc.)
• Review component styling changes (sizes, spacing, border radius)
• Update custom theme overrides to CSS variables
• Test visual appearance and adjust as needed

Testing

• Visual regression testing
• Functionality testing
• Accessibility testing
• Performance testing

Common Issues and Solutions

Issue: Components not rendering

Solution: Ensure you've imported @heroui/styles in your CSS file and it's imported after tailwindcss.

Issue: Styles not applying

Solution: Check that Tailwind CSS v4 is properly configured and CSS imports are in the correct order.

Issue: TypeScript errors

Solution: Update your TypeScript types. v3 may have different prop types. Check component documentation.

Issue: Animations not working

Solution: v3 handles animations differently. Check if the component supports animations in v3.

Getting Help

If you encounter issues during migration:

1. Check the v3 documentation
2. Review component-specific documentation
3. Check the GitHub Discussions
4. Join the Discord community

Next Steps

After completing the migration:

1. Review the v3 component documentation
2. Explore new components available in v3
3. Check out the styling guide
4. Learn about composition patterns