Incremental Migration

Overview

Incremental migration with coexistence allows you to migrate from HeroUI v2 to v3 component-by-component while keeping your project functional throughout the migration process. This approach uses special setup strategies to allow both v2 and v3 components to work side-by-side.

AI Assistant Resources

AI assistants can help with migration. Use the Migration MCP Server for tools and prompts, Migration Agent Skills for skill-based knowledge, or AGENTS.md for Migration to download migration docs into your project.

Limitations and Considerations

Before choosing this approach, be aware of:

• Bundle Size: Both versions will be included during migration, increasing bundle size
• Styling Conflicts: v2 and v3 styles may conflict; test thoroughly
• Type Conflicts: TypeScript may show conflicts if both versions are imported in the same file
• Provider: v2 requires HeroUIProvider, v3 doesn't - you may need conditional provider wrapping
• React Version: v3 requires React 19+, v2 supports React 18+ - ensure React 19 is installed
• Setup Complexity: Requires more complex initial setup compared to full migration

Components Without v3 Counterparts

Since v2 and v3 can coexist, v2 components that have no v3 counterpart can remain in your project. These components will continue to work during migration:

• Code, Image, Navbar, Ripple, Snippet, Spacer, User

You do not need to replace them to complete the migration. If you prefer to remove them and use native HTML or manual implementations instead, you may ask your agent to help using the Component Migration Reference guides.

Strategy Selection

Choose your strategy based on how you currently import v2 components:

• Using @heroui/react: Use Strategy A (pnpm aliases)
• Using component packages (@heroui/button, @heroui/card, etc.): Use Strategy B (component packages)

Strategy A: Using pnpm Aliases

This strategy uses pnpm package aliases to install v3 packages under different names, allowing both versions to coexist.

Setup

1. Install v3 packages with aliases:

{
  "dependencies": {
    "@heroui/react": "2.8.6",
    "@heroui/theme": "2.4.24",
    "@heroui-v3/react": "npm:@heroui/react@latest",
    "@heroui-v3/styles": "npm:@heroui/styles@latest"
  }
}

2. Import v2 components from @heroui/react:

import {Button} from "@heroui/react"; // v2

3. Import v3 components from @heroui-v3/react:

import {Button} from "@heroui-v3/react"; // v3

Migration Process

1. Migrate one component at a time:

   • Update imports to use @heroui-v3/react
   • Update component code to v3 API
   • Test the migrated component
   • Verify styling looks correct
   • For v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User), leave them in place. They will continue to work during coexistence.

2. Continue until all components are migrated

   • Track which components have been migrated
   • Test each migrated component thoroughly
   • If you want to remove v2 removed components later, use the Component Migration Reference guides and ask your agent to help replace them with native HTML or manual implementations.

3. Once all components are migrated, switch to v3-only:

   • Remove v2 dependencies (@heroui/react, @heroui/theme)
   • Remove aliases
   • Update all imports to @heroui/react (remove -v3 suffix)
   • Complete styling migration

Considerations

• Both CSS systems will be loaded (v2 via Tailwind plugin, v3 via CSS import)
• You'll need both Tailwind configs temporarily
• Bundle size will be larger during migration
• Some styling conflicts may occur

Strategy B: Using Component Packages

This strategy uses v2's component-specific packages alongside v3's unified package.

Setup

1. Install v3 main package and v2 component packages:

{
  "dependencies": {
    "@heroui/react": "latest", // v3
    "@heroui/styles": "latest", // v3
    "@heroui/button": "2.8.6", // v2
    "@heroui/card": "2.8.6", // v2
    // ... other v2 component packages as needed
  }
}

2. Import v3 components from @heroui/react:

import {Button} from "@heroui/react"; // v3

3. Import v2 components from component packages:

import {Card} from "@heroui/card"; // v2

Migration Process

1. Install v3 packages (@heroui/react, @heroui/styles)
2. Install v2 component packages for components not yet migrated
3. Migrate one component at a time:
   • Remove the v2 component package from dependencies
   • Update imports to use @heroui/react (v3)
   • Update component code to v3 API
   • Test the migrated component
   • For v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User), leave them in place. They will continue to work during coexistence.
4. Continue until all components are migrated
   • If you want to remove v2 removed components later, use the Component Migration Reference guides and ask your agent to help replace them with native HTML or manual implementations.
5. Remove remaining v2 component packages
6. Complete styling migration

Considerations

• Only works if your project uses component-specific packages
• Requires managing multiple package dependencies
• v3 doesn't have component packages, so this is a one-way migration path

CSS Configuration for Coexistence

During coexistence, you'll need both CSS systems:

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

/* v2 styles via Tailwind plugin */
/* (configured in tailwind.config.js) */

/* v3 styles */
@import "@heroui/styles";

Tailwind Configuration

You'll need both Tailwind configs temporarily:

v2 Config (tailwind.config.js):

const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [heroui()],
  // ... other config
};

v3 Config: No plugin needed, but ensure Tailwind v4 is installed.

Component Migration

For each component you migrate:

1. Review the component migration guide

   • Use the Component Migration Reference table
   • Check component-specific migration guides

2. Update imports

   • Strategy A: Change @heroui/react → @heroui-v3/react
   • Strategy B: Change component package → @heroui/react

3. Update component code

   • Follow component migration guide
   • Update props, component structure, and API calls
   • Replace hooks with compound components if needed

4. Test the migrated component

   • Verify component renders correctly
   • Test functionality and interactions
   • Check for styling conflicts
   • Ensure v2 components still styled correctly

5. Document migration

   • Track which components have been migrated
   • Note any issues or concerns

CSS Conflict Handling

During coexistence, both v2 and v3 CSS systems will be loaded. Monitor for conflicts:

1. Watch for styling inconsistencies

   • Check if v2 and v3 styles are conflicting
   • Verify both CSS imports are present and in correct order

2. Guide conflict resolution

   • Ensure CSS import order: tailwindcss first, then @heroui/styles
   • Check Tailwind config has v2 plugin configured
   • Verify v3 CSS is imported correctly

3. Test styling after each migration

   • Verify migrated components look correct
   • Check for unexpected style overrides
   • Ensure v2 components still styled correctly

Completing the Migration

Once all components are migrated:

1. Remove v2 dependencies:

   • Remove @heroui/react and @heroui/theme (Strategy A)
   • Remove all @heroui/* component packages (Strategy B)
   • Remove aliases (Strategy A)
   • If you left v2 removed components in place (Code, Image, Navbar, Ripple, Snippet, Spacer, User), you have two options: (1) Replace them per the migration guides before removing v2 dependencies, or (2) Keep v2 dependencies until you are ready to replace them. You may ask an agent to help remove them using the provided guides.

2. Update all imports:

   • Change @heroui-v3/react → @heroui/react (Strategy A)
   • Change component package imports → @heroui/react (Strategy B)

3. Update CSS:

   • Remove v2 Tailwind plugin from config
   • Keep only @import "@heroui/styles";

4. Complete styling migration:

   • Follow the Styling Migration Guide
   • Update utility classes, color tokens, etc.

Migration Checklist for Coexistence

Use this checklist to track your incremental migration progress:

Initial Setup

• Choose strategy (A: aliases or B: component packages)
• Install v3 packages (with aliases or directly)
• Configure CSS for both versions
• Ensure React 19+ is installed
• Set up both Tailwind configs temporarily

Component Migration (Repeat for each component)

• Review component migration guide
• Update imports (Strategy A or B)
• Update component code to v3 API
• Test the migrated component
• Check for styling conflicts
• Document migration progress
• Identify v2 removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User) — leave in place or replace per guides

Completion

• Migrate all components
• Optional: Replace removed components using migration guides before removing v2 deps, or remove v2 deps only after all removed components are replaced
• Remove v2 dependencies
• Remove aliases (Strategy A)
• Update all imports to v3-only
• Remove v2 Tailwind plugin
• Update CSS to v3-only
• Complete styling migration
• Test entire application

Next Steps

After completing the incremental 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