Overview
Nuxt UI v3 is a complete rewrite built on top of Reka UI, Tailwind CSS, and Tailwind Variants. This migration brings significant improvements in accessibility, theming, and developer experience.Breaking Changes
Migration to Reka UI
The biggest change in v3 is the migration from Headless UI to Reka UI for all component primitives. Key Changes:- All components now use Reka UI primitives for better accessibility
- Component APIs have been updated to match Reka UI patterns
- Some props and events have been renamed for consistency
Modal and Overlay Changes
useOverlay API Changes
The overlay system has been completely redesigned for programmatic control of modals and slideovers. Before (v2):The
.open() method now returns a promise that resolves when the overlay closes.Prevent Close Renamed to Dismissible
Theprevent-close prop has been renamed to dismissible and its logic inverted.
Before (v2):
Form Validation Changes
Nested Form State
Nested forms now include their state in the parent form’s submit data. Migration:- Review nested form structures
- Update submit handlers to account for nested form data
Validation Schema Changes
Form validation now uses a standard schema interface. Before (v2):Component Changes
Devtools Removed
The built-in devtools have been removed in favor of Compodium. Migration:ColorPicker Migration
ColorPicker now usescolortranslator instead of the color library.
Impact:
- Color format handling has changed
- API for color manipulation is different
- Review color-related code if using ColorPicker programmatically
Toast Changes
Toast Events Renamed
Theclick event has been renamed to onClick for consistency.
Before (v2):
useToast No Longer Returns Promise
Theadd method no longer returns a promise.
Before (v2):
Table Component
Select Event Added
The Table component now has a@select event for row selection.
Theme System
Tailwind Variants Integration
The theme system now uses Tailwind Variants for better type safety and variant composition. app.config.ts:Semantic Color Tokens
v3 introduces semantic color tokens for better theme consistency. Before (v2):Semantic tokens adapt automatically to light/dark mode and theme changes.
Alert and Toast Orientation
The Alert and Toast components now have anorientation prop.
New Features
Tree Component
A new Tree component for displaying hierarchical data.InputNumber Component
A new component for numeric input with increment/decrement controls.PinInput Component
A new component for PIN or OTP input.Calendar Component
A new Calendar component for date selection.ColorPicker Component
A redesigned color picker with better UX.Stepper Component
A new component for multi-step workflows.Timeline Component
A new component for displaying chronological data.CheckboxGroup Component
A new component for managing multiple checkboxes.InputTags Component
A new component for tag input.FileUpload Component
A new component for file uploads with preview.Internationalization
v3 includes built-in i18n support with multiple languages.- English (default)
- Spanish
- French
- German
- Italian
- Japanese
- Chinese
- Korean
- Arabic
- And many more…
Custom Locale
You can extend or create custom locales:Accessibility Improvements
ARIA Attributes
All components now include proper ARIA attributes:aria-labelandaria-labelledbyaria-describedbyfor form fieldsaria-invalidfor form validation- Proper
roleattributes
Keyboard Navigation
Enhanced keyboard navigation for all interactive components:- Arrow keys for menus and dropdowns
- Enter/Space for buttons and checkboxes
- Escape for closing modals and overlays
- Tab for focus management
Focus Management
Improved focus management:- Focus trapping in modals
- Proper focus restoration
- Visible focus indicators
Migration Checklist
Update dependencies
- Update @nuxt/ui to v3
- Review and update any UI-related dependencies
Update modal and overlay usage
- Replace useModal with useOverlay
- Update prevent-close to dismissible
- Handle promise-based overlay API
Update form validation
- Migrate to zod or valibot
- Update schema definitions
- Test nested form behavior
Update theme customization
- Migrate to Tailwind Variants format
- Update color tokens to semantic names
- Test light/dark mode
Update component usage
- Review Toast event handlers
- Update ColorPicker if used
- Add orientation props where needed
Test accessibility
- Test keyboard navigation
- Test screen reader compatibility
- Verify ARIA attributes
Test application
- Run full test suite
- Test all forms
- Test all interactive components
- Verify responsive behavior
Resources
Need Help?
If you encounter issues during migration:- Check the GitHub Discussions
- Review the Changelog
- Open an issue on GitHub