// HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI.
HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind, mobile components.
HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles.
| name | heroui-migration |
| description | HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI. |
| metadata | {"author":"heroui","version":"2.0.0","status":"preview"} |
This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.
curl -fsSL https://heroui.com/install | bash -s heroui-migration
Do NOT assume v2 patterns work in v3. Always fetch migration guides before implementing 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 |
For migration details, examples, and step-by-step guides, always fetch documentation:
# 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.mjs
Migration docs (preview): https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}
Examples:
.../agent-guide-full.mdx.../agent-guide-incremental.mdx.../button.mdx.../styling.mdx.../hooks.mdxOverride base URL with HEROUI_MIGRATION_DOCS_BASE when docs are merged to production.
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"
}
}
}
Always fetch the agent guide before starting: node scripts/get_migration_guide.mjs full or incremental
Card.Header, Card.Title, Button with children—not flat propsHeroUIProvider when migratingonPressnode scripts/get_migration_guide.mjs fullnode scripts/get_styling_migration_guide.mjsThis 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.