Skip to main content

​
Overview

Nuxt UI v4 is a major release that brings compatibility with Nuxt 4, imports @nuxt/ui-pro components into the main library, and introduces several breaking changes to improve consistency and developer experience.
Nuxt UI v4 requires Nuxt 4 for compatibility. Ensure you’ve upgraded your Nuxt version before migrating.

​
Breaking Changes

​
Nuxt 4 Compatibility

The most significant change in v4 is the update to support Nuxt 4. This means v4 is not compatible with Nuxt 3.
1

​
Update Nuxt to v4

First, upgrade your Nuxt application to version 4:
npm install nuxt@^4.0.0
2

​
Update Nuxt UI to v4

npm install @nuxt/ui@^4.0.0

​
Component Renames and Removals

​
FieldGroup (formerly ButtonGroup)

The ButtonGroup component has been renamed to FieldGroup to better reflect its purpose in form layouts. Before (v3): 
<UButtonGroup>
  <UButton>First</UButton>
  <UButton>Second</UButton>
</UButtonGroup>
After (v4): 
<UFieldGroup>
  <UButton>First</UButton>
  <UButton>Second</UButton>
</UFieldGroup>

​
Marquee (formerly PageMarquee)

The PageMarquee component has been simplified and renamed to Marquee. Before (v3): 
<UPageMarquee :items="items" />
After (v4): 
<UMarquee :items="items" />

​
PageAccordion Removed

The PageAccordion component has been removed in favor of the standard Accordion component. Before (v3): 
<UPageAccordion :items="items" />
After (v4): 
<UAccordion :items="items" />

​
AI SDK v5 Upgrade

If you’re using AI-related components, they now use ai-sdk v5, which includes breaking changes to the AI SDK API.
Review the Vercel AI SDK v5 migration guide for details on API changes.

​
Model Modifiers

The nullify modifier has been renamed to nullable, and a new optional modifier has been added. Before (v3): 
<UInput v-model.nullify="value" />
After (v4): 
<UInput v-model.nullable="value" />
<!-- Or use optional if you want undefined instead of null -->
<UInput v-model.optional="value" />

​
Form Validation Changes

Support for joi and yup has been removed in favor of the @standard-schema/spec interface. This means you should migrate to validation libraries that support the standard schema spec. Before (v3): 
import * as yup from 'yup'

const schema = yup.object({
  email: yup.string().email().required()
})
After (v4): 
import { z } from 'zod'

const schema = z.object({
  email: z.string().email()
})
Zod and Valibot are recommended alternatives that support the standard schema specification.

​
Form State Transformation

The Form component no longer mutates the form state when transformations are enabled. This prevents unwanted side effects. Migration:
  • If you rely on the form state being transformed, you’ll need to handle transformations manually in your submit handler.
  • Consider using the transform prop with a separate transformed state variable.

​
Table Select Event

The arguments order in the @select event has been standardized for consistency. Before (v3): 
<UTable @select="(item, selected) => handleSelect(item, selected)" />
After (v4): 
<UTable @select="(selected, item) => handleSelect(selected, item)" />

​
CommandPalette Children Icon

The trailing-icon prop in the input is now separate from the children-icon prop. Before (v3): 
<UCommandPalette trailing-icon="i-heroicons-chevron-down" />
After (v4): 
<UCommandPalette 
  trailing-icon="i-heroicons-search" 
  children-icon="i-heroicons-chevron-down" 
/>

​
Consistent Exposed Refs

Component refs have been standardized across all components. Some components now expose different ref names. Migration:
  • Check your template refs if you’re accessing component internals
  • Refer to the component documentation for the new exposed ref structure

​
Composables Export

Composables are now properly exported from the module, which may affect your import statements. Before (v3): 
import { useToast } from '#imports'
After (v4): 
import { useToast } from '@nuxt/ui'

​
New Features

​
Nuxt UI Pro Components Integrated

All components from @nuxt/ui-pro have been integrated into the main @nuxt/ui package. You no longer need to install @nuxt/ui-pro separately.
1

​
Remove @nuxt/ui-pro

npm uninstall @nuxt/ui-pro
2

​
Update imports

All pro components are now available from @nuxt/ui:
<template>
  <UDashboardPanel>
    <UDashboardNavbar />
    <UDashboardSidebar />
  </UDashboardPanel>
</template>

​
Icon Component Enhancement

The Icon component now allows passing a component instead of just a name string. 
<template>
  <UIcon :name="CustomIconComponent" />
</template>

​
New Components

​
Editor Component

A new rich text editor component with full WYSIWYG capabilities. 
<template>
  <UEditor v-model="content" />
</template>

​
Theme Component

A new component for managing theme configurations. 
<template>
  <UTheme />
</template>

​
Empty Component

A dedicated component for displaying empty states. 
<template>
  <UEmpty 
    title="No results found" 
    description="Try adjusting your search criteria"
  />
</template>

​
InputDate and InputTime

New date and time input components for better form handling. 
<template>
  <UInputDate v-model="date" />
  <UInputTime v-model="time" />
</template>

​
ScrollArea Component

A new component for creating custom scrollable areas with better styling control. 
<template>
  <UScrollArea>
    <!-- Long content -->
  </UScrollArea>
</template>

​
Deprecations

​
useOverlay Changes

The unmount function has been renamed from unmont (fixing the typo). Before (v3): 
const { unmont } = useOverlay()
After (v4): 
const { unmount } = useOverlay()

​
Migration Checklist

1

​
Update dependencies

  • Upgrade Nuxt to v4
  • Upgrade @nuxt/ui to v4
  • Remove @nuxt/ui-pro if installed
2

​
Update component names

  • Replace UButtonGroup with UFieldGroup
  • Replace UPageMarquee with UMarquee
  • Replace UPageAccordion with UAccordion
3

​
Update validation schemas

  • Migrate from joi/yup to zod or valibot
  • Update form schemas to use @standard-schema/spec
4

​
Update model modifiers

  • Replace .nullify with .nullable or .optional
5

​
Update event handlers

  • Fix Table @select event argument order
6

​
Update composable imports

  • Import composables directly from ‘@nuxt/ui’
7

​
Test your application

  • Run npm run dev and check for errors
  • Test all forms and validation
  • Test all UI components
  • Run type checking with npm run typecheck

​
Need Help?

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us