Migration

For AI Assistants

Below are three approaches for AI assistants to access migration documentation. We recommend using the HeroUI Migration MCP server and leveraging its prompts and tools, but all options provide agents with the complete documentation.

Major Changes

• Dependencies: Update React to v19+, HeroUI packages to v3, Tailwind CSS to v4, remove Framer Motion
• No Provider Required: v3 removes the need for HeroUIProvider
• Component API Updates: Many components use React Aria Components patterns
• Compound Components: New compound component patterns for better customization. See individual component guides for details.
• Hooks Removed: v2 component hooks like useSwitch or useInput are removed - use compound components instead. useDisclosure is replaced with useOverlayState. See the Hooks Migration Guide for details.
• Configuration: Remove heroui() plugin from Tailwind config, update CSS imports, remove hero.ts file
• Item identity: Collection items (Dropdown, Listbox, Select, Accordion, etc.) now use id and textValue in v3; keep React's key for lists.

Item identity and accessibility (key, id, textValue)

In v2, collection components (Dropdown, Listbox, Select, Accordion, etc.) used React's key as the item identity. The same value drove both React's list reconciliation and the component's selection/expand state. In v3, which uses React Aria Components, those roles are split:

• id — v3 uses an explicit id prop on each item for selection state, focus, and callbacks (e.g. selectedKeys, expandedKeys, onSelectionChange). Use the same (or equivalent) value you used for key in v2 so that state and callbacks continue to refer to the correct item.
• textValue — v3 requires textValue on items when the visible content is not plain text (e.g. when using Label, icons, or Description). It is used for screen reader announcements and type-ahead.
• key — Keep using React's key on list items. It is still required for React's reconciliation and is independent of id.

When migrating: add id (and textValue where needed) for v3's API, but keep key for React.

Migration Strategies

HeroUI v2 and v3 cannot coexist in the same project without special setup. You have two migration approaches to choose from:

Full Migration

Best for: Projects that can dedicate focused time to complete migration in one go.

How it works:

• Migrate all component code first (project will be broken during this phase)
• Switch dependencies to v3
• Complete styling migration

Advantages:

• Simpler setup - no complex coexistence configuration
• Cleaner transition - only one version active at a time
• Supported by Migration MCP prompts

Disadvantages:

• Project is broken during migration
• All components should be migrated before switching dependencies

Get started: Full Migration Guide

Incremental Migration

Best for: Projects that need to stay functional during migration, teams migrating gradually over time, large codebases migrating feature-by-feature.

How it works:

• Set up coexistence using pnpm aliases or component packages
• Migrate components one-by-one while keeping project functional
• Complete migration and remove v2 dependencies

Advantages:

• Project remains functional during migration
• Can migrate gradually over time
• Can test v3 components alongside v2

Disadvantages:

• More complex initial setup
• Potential styling conflicts
• Requires managing two versions simultaneously

Get started: Incremental Migration Guide

Component Migration Reference

Use the table below to quickly find migration guidance for each component. Use the link in the "Migration Guide" column to jump to detailed migration instructions.

Component Development Status: Components marked with 🔄 In Progress or 📋 Planned are still being developed. Check the Roadmap for the task status. Guides for these components will be available once development is finished.

v2 Component	v3 Component	Status	Migration Guide
Accordion	Accordion	✅ Available	View guide →
Alert	Alert	✅ Available	View guide →
Autocomplete	ComboBox	✅ Renamed	View guide →
Avatar	Avatar	✅ Available	View guide →
Badge	Badge	✅ Available	View guide →
Breadcrumbs	Breadcrumbs	✅ Available	View guide →
Button	Button	✅ Available	View guide →
ButtonGroup	ButtonGroup	✅ Available	View guide →
Calendar	Calendar	✅ Available	View guide →
Card	Card	✅ Available	View guide →
Checkbox	Checkbox	✅ Available	View guide →
CheckboxGroup	CheckboxGroup	✅ Available	View guide →
Chip	Chip	✅ Available	View guide →
Code	❌	❌ Removed	View guide →
DateInput	DateField	✅ Renamed	View guide →
DatePicker	DatePicker	✅ Available	View guide →
DateRangePicker	DateRangePicker	✅ Available	View guide →
TimeInput	TimeField	✅ Renamed	View guide →
Divider	Separator	✅ Renamed	View guide →
Drawer	Drawer	✅ Available	View guide →
Dropdown	Dropdown	✅ Available	View guide →
Form	Form	✅ Available	View guide →
Image	❌	❌ Removed	View guide →
Input	TextField, Input, InputGroup	✅ Available	View guide →
InputOTP	InputOTP	✅ Available	View guide →
Kbd	Kbd	✅ Available	View guide →
Link	Link	✅ Available	View guide →
Listbox	ListBox	✅ Available	View guide →
Modal	Modal	✅ Available	View guide →
Navbar	❌	❌ Removed	View guide →
NumberInput	NumberField	✅ Renamed	View guide →
Pagination	Pagination	✅ Available	View guide →
Popover	Popover	✅ Available	View guide →
Progress	ProgressBar	✅ Renamed	View guide →
CircularProgress	ProgressCircle	✅ Renamed	View guide →
Radio	Radio	✅ Available	View guide →
RadioGroup	RadioGroup	✅ Available	View guide →
RangeCalendar	RangeCalendar	✅ Available	View guide →
Ripple	❌	❌ Removed	See Button ripple →
ScrollShadow	ScrollShadow	✅ Available	View guide →
Select	Select	✅ Available	View guide →
Skeleton	Skeleton	✅ Available	View guide →
Slider	Slider	✅ Available	View guide →
Snippet	❌	❌ Removed	View guide →
Spacer	❌	❌ Removed	View guide →
Spinner	Spinner	✅ Available	View guide →
Switch	Switch	✅ Available	View guide →
Table	Table	✅ Available	View guide →
Tabs	Tabs	✅ Available	View guide →
Toast	Toast	✅ Available	View guide →
Tooltip	Tooltip	✅ Available	View guide →
User	❌	❌ Removed	View guide →

New Components in v3

v3 introduces a number of new components not available in v2:

Component	Purpose	Documentation
TextField	Enhanced text input with label and description support	View docs →
TextArea	Multi-line text input component	View docs →
AlertDialog	Modal dialog for confirmations and alerts	View docs →
Label	Accessible form label component	View docs →
Description	Helper text for form fields	View docs →
FieldError	Form field error message display	View docs →
Fieldset	Group related form fields	View docs →
InputGroup	Compose multiple inputs together	View docs →
Surface	Container component with elevation styles	View docs →
Disclosure	Expandable/collapsible content sections	View docs →
DisclosureGroup	Compound component for multiple disclosure sections	View docs →
SearchField	Search input with clear button and optional loading state	View docs →
DateField	Date input with calendar picker	View docs →
TimeField	Time input component	View docs →
Tag, TagGroup	Tags and tag group for selection or display	View docs →
ColorPicker	Color selection (ColorArea, ColorField, ColorSlider, ColorSwatch, ColorSwatchPicker)	View docs →
CloseButton	Dismiss or close trigger button	View docs →
ErrorMessage	Form field error display (React Aria integration)	View docs →

Additional Migration Guides

• Hooks Migration Guide: Detailed guide for migrating hooks from v2 to v3
• Styling Migration Guide: Comprehensive guide for updating utility classes, color tokens, and component styling

Getting Help

If you encounter issues during migration:

1. Check the v3 documentation
2. Review component-specific migration guides
3. Check the GitHub Discussions
4. Join the Discord community