HeroUI v2 to v3 Migration Guide
This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.
Installation
curl -fsSL https://heroui.com/install | bash -s heroui-migrationCRITICAL: Always Fetch Migration Docs Before Applying
Do NOT assume v2 patterns work in v3. Always fetch migration guides before implementing changes.
Key v2 → v3 Changes
| Feature | v2 (Migrate From) | v3 (Migrate To) |
|---|---|---|
| Provider | <HeroUIProvider> required | No Provider needed |
| Component API | Flat props: <Card title="x"> | Compound: <Card><Card.Header> |
| Event handlers | onClick | onPress |
| Styling | classNames prop | className prop |
| Hooks | useSwitch, useDisclosure, etc. | Compound components, useOverlayState |
| Packages | @heroui/system, @heroui/theme | @heroui/react, @heroui/styles |
Accessing Migration Documentation
For migration details, examples, and step-by-step guides, always fetch documentation:
Using Scripts
# List all available component migration guides
node scripts/list_migration_guides.mjs
# Get main migration workflow (full or incremental)
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental
# Get component-specific migration guides
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal
# Get styling migration guide
node scripts/get_styling_migration_guide.mjs
# Get hooks migration guide
node scripts/get_hooks_migration_guide.mjsDirect URLs
Migration docs (preview): https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}
Examples:
- Full migration:
.../agent-guide-full.mdx - Incremental:
.../agent-guide-incremental.mdx - Button:
.../button.mdx - Styling:
.../styling.mdx - Hooks:
.../hooks.mdx
Override base URL with HEROUI_MIGRATION_DOCS_BASE when docs are merged to production.
MCP Alternative
When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:
{
"mcpServers": {
"heroui-migration": {
"url": "https://migration-mcp.heroui.com"
}
}
}Migration Strategies
Full Migration
- Best for: Projects that can dedicate focused time; teams comfortable with temporarily broken code
- Migrate all component code first (project broken during migration)
- Switch dependencies to v3
- Complete styling migration
Incremental Migration
- Best for: Projects that must stay functional; large codebases migrating gradually
- Set up coexistence (pnpm aliases or component packages)
- Migrate components one-by-one
- Both v2 and v3 coexist during migration
Always fetch the agent guide before starting: node scripts/get_migration_guide.mjs full or incremental
Core Principles
- Fetch first: Use scripts to get migration guides before applying changes
- Compound components: v3 uses
Card.Header,Card.Title,Buttonwith children—not flat props - No Provider: Remove
HeroUIProviderwhen migrating - onPress not onClick: All interactive components use
onPress - Workflow: Analyze → Migrate components → Switch deps → Styling migration
Migration Workflow Summary
- Create migration branch
- Analyze project (HeroUI imports, component usage)
- Fetch main guide:
node scripts/get_migration_guide.mjs full - Migrate components in batches (fetch component guides per batch)
- Switch dependencies to v3
- Fetch styling guide:
node scripts/get_styling_migration_guide.mjs - Apply styling updates
Preview Mode
This skill targets the staging deployment of the docs/migration branch. Once docs are merged to main and live on heroui.com, set HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration or update the default in scripts.