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-migration
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/s… |
