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 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 CRITICAL: 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 Direct URLs Migration docs (preview): use a concrete guide URL from the examples below, and never fetch a URL that still contains a placeholder. 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: 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 1. Fetch first : Use scripts to get migration guides before applying changes 2. Compound components : v3 uses Card.Header , Card.Title , Button with children—not flat props 3. No Provider : Remove HeroUIProvider when migrating 4. onPress not onClick : All interactive components use onPress 5. Workflow : Analyze → Migrate components → Switch deps → Styling migration Migration Workflow Summary 1. Create migration branch 2. Analyze project (HeroUI imports, component usage) 3. Fetch main guide: node scripts/get migration guide.mjs full 4. Migrate components in batches (fetch component guides per batch) 5. Switch dependencies to v3 6. Fetch styling guide: node scripts/get styling migration guide.mjs 7. 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.

heroui-migration