Migration to v3

A comprehensive guide to migrate your application from Nuxt UI v2 to Nuxt UI v3.

Nuxt UI v3 is a new major version rebuilt from the ground up, introducing a modern architecture with significant performance improvements and an enhanced developer experience. This major release includes several breaking changes alongside powerful new features and capabilities:

Tailwind CSS v4: Migration from JavaScript to CSS-based configuration
Reka UI: Replacing Headless UI as the underlying component library
Tailwind Variants: New styling API for component variants

This guide provides step by step instructions to migrate your application from v2 to v3.

Migrate your project

Update Tailwind CSS

Tailwind CSS v4 introduces significant changes to its configuration approach. The official Tailwind upgrade tool will help automate most of the migration process.

For a detailed walkthrough of all changes, refer to the official Tailwind CSS v4 upgrade guide.

Create a main.css file and import it in your nuxt.config.ts file:

@import "tailwindcss";

export default defineNuxtConfig({
  css: ['~/assets/css/main.css']
})

Run the Tailwind CSS upgrade tool:

npx @tailwindcss/upgrade

Update Nuxt UI

Install the latest version of the package:

pnpm add @nuxt/ui

yarn add @nuxt/ui

npm install @nuxt/ui

bun add @nuxt/ui

Import it in your CSS:

app/assets/css/main.css

@import "tailwindcss";
@import "@nuxt/ui";

Wrap your app with the App component:

app.vue

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

Changes from v2

Now that you have updated your project, you can start migrating your code. Here's a comprehensive list of all the breaking changes in Nuxt UI v3.

Updated design system

In Nuxt UI v2, we had a mix between a design system with primary, gray, error aliases and all the colors from Tailwind CSS. We've replaced it with a proper design system with 7 color aliases:

Color	Default	Description
`primary`	`green`	Main brand color, used as the default color for components.
`secondary`	`blue`	Secondary color to complement the primary color.
`success`	`green`	Used for success states.
`info`	`blue`	Used for informational states.
`warning`	`yellow`	Used for warning states.
`error`	`red`	Used for form error validation states.
`neutral`	`slate`	Neutral color for backgrounds, text, etc.

This change introduces several breaking changes that you need to be aware of:

The gray color has been renamed to neutral

<template>
- <p class="text-gray-500 dark:text-gray-400" />
+ <p class="text-neutral-500 dark:text-neutral-400" />
</template>

You can also use the new design tokens to handle light and dark mode:

<template>
- <p class="text-gray-500 dark:text-gray-400" />
+ <p class="text-muted" />

- <p class="text-gray-900 dark:text-white" />
+ <p class="text-highlighted" />
</template>

The gray, black and white in the color props have been removed in favor of neutral:

- <UButton color="black" />
+ <UButton color="neutral" />

- <UButton color="gray" />
+ <UButton color="neutral" variant="subtle" />

- <UButton color="white" />
+ <UButton color="neutral" variant="outline" />

You can no longer use Tailwind CSS colors in the color props, use the new aliases instead:

- <UButton color="red" />
+ <UButton color="error" />

Learn how to extend the design system to add new color aliases.

The color configuration in app.config.ts has been moved into a colors object:

export default defineAppConfig({
  ui: {
-   primary: 'green',
-   gray: 'cool'
+   colors: {
+     primary: 'green',
+     neutral: 'slate'
+   }
  }
})

Updated theming system

Nuxt UI components are now styled using the Tailwind Variants API, which makes all the overrides you made using the app.config.ts and the ui prop obsolete.

Update your app.config.ts to override components with their new theme:

export default defineAppConfig({
   ui: {
     button: {
-       font: 'font-bold',
-       default: {
-         size: 'md',
-         color: 'primary'
-       }
+       slots: {
+         base: 'font-medium'
+       },
+       defaultVariants: {
+         size: 'md',
+         color: 'primary'
+       }
     }
   }
})

Update your ui props to override each component's slots using their new theme:

<template>
- <UButton :ui="{ font: 'font-bold' }" />
+ <UButton :ui="{ base: 'font-bold' }" />
</template>

We can't detail all the changes here but you can check each component's theme in the Theme section.

Renamed components

We've renamed some Nuxt UI components to align with the Reka UI naming convention:

v2	v3
`Divider`	`Separator`
`Dropdown`	`DropdownMenu`
`FormGroup`	`FormField`
`Range`	`Slider`
`Toggle`	`Switch`
`Meter`	Removed
`Notification`	`Toast`
`Radio`	Removed (use `RadioGroup` instead)
`VerticalNavigation`	`NavigationMenu` with `orientation="vertical"`
`HorizontalNavigation`	`NavigationMenu` with `orientation="horizontal"`

Here are the Nuxt UI Pro components that have been renamed or removed:

v1	v3
`BlogList`	`BlogPosts`
`ColorModeToggle`	`ColorModeSwitch`
`DashboardCard`	Removed (use `PageCard` instead)
`DashboardLayout`	`DashboardGroup`
`DashboardModal`	Removed (use `Modal` instead)
`DashboardNavbarToggle`	`DashboardSidebarToggle`
`DashboardPage`	Removed
`DashboardPanelContent`	Removed (use `#body` slot instead)
`DashboardPanelHandle`	`DashboardResizeHandle`
`DashboardSection`	Removed (use `PageCard` instead)
`DashboardSidebarLinks`	Removed (use `NavigationMenu` instead)
`DashboardSlideover`	Removed (use `Slideover` instead)
`FooterLinks`	Removed (use `NavigationMenu` instead)
`HeaderLinks`	Removed (use `NavigationMenu` instead)
`LandingCard`	Removed (use `PageCard` instead)
`LandingCTA`	`PageCTA`
`LandingFAQ`	Removed (use `Accordion` instead)
`LandingGrid`	Removed (use `PageGrid` instead)
`LandingHero`	Removed (use `PageHero` instead)
`LandingLogos`	`PageLogos`
`LandingSection`	`PageSection`
`LandingTestimonial`	Removed (use `PageCard` instead)
`NavigationAccordion`	`ContentNavigation`
`NavigationLinks`	`ContentNavigation`
`NavigationTree`	`ContentNavigation`
`PageError`	`Error`
`PricingCard`	`PricingPlan`
`PricingGrid`	`PricingPlans`
`PricingSwitch`	Removed (use `Switch` or `Tabs` instead)

Changed components

In addition to the renamed components, there are lots of changes to the components API. Let's detail the most important ones:

The links and options props have been renamed to items for consistency:

<template>
- <USelect :options="countries" />
+ <USelect :items="countries" />

- <UHorizontalNavigation :links="links" />
+ <UNavigationMenu :items="links" />
</template>

This change affects the following components: Breadcrumb, HorizontalNavigation, InputMenu, RadioGroup, Select, SelectMenu, VerticalNavigation.

The click field in different components has been removed in favor of the native Vue onClick event:

<script setup lang="ts">
const items = [{
  label: 'Edit',
-  click: () => {
+  onClick: () => {
    console.log('Edit')
  }
}]
</script>

This change affects the Toast component as well as all component that have items links like NavigationMenu, DropdownMenu, CommandPalette, etc.

The global Modals, Slideovers and Notifications components have been removed in favor of the App component:

app.vue

<template>
+  <UApp>
+    <NuxtPage />
+  </UApp>
-  <UModals />
-  <USlideovers />
-  <UNotifications />
</template>

The v-model:open directive and default-open prop are now used to control visibility:

<template>
- <UModal v-model="open" />
+ <UModal v-model:open="open" />
</template>

This change affects the following components: ContextMenu, Modal and Slideover and enables controlling visibility for InputMenu, Select, SelectMenu and Tooltip.

The default slot is now used for the trigger and the content goes inside the #content slot (you don't need to use a v-model:open directive with this method):

<script setup lang="ts">
- const open = ref(false)
</script>

<template>
- <UButton label="Open" @click="open = true" />

- <UModal v-model="open">
+ <UModal>
+   <UButton label="Open" />

+   <template #content>
      <div class="p-4">
        <Placeholder class="h-48" />
      </div>
+   </template>
  </UModal>
</template>

This change affects the following components: Modal, Popover, Slideover, Tooltip.

A #header, #body and #footer slots have been added inside the #content slot like:

<template>
- <UModal>
+ <UModal title="Title" description="Description">
-   <div class="p-4">
+   <template #body>
      <Placeholder class="h-48" />
+   </template>
-   </div>
  </UModal>
</template>

This change affects the following components: Modal, Slideover.

The prevent-close prop has been removed in favor of the dismissible prop:

<template>
- <UModal prevent-close />
+ <UModal :dismissible="false" />
</template>

This change affects the following components: Modal, Slideover.

The Pagination component v-model directive has been renamed to v-model:page:

<template>
- <UPagination v-model="page" />
+ <UPagination v-model:page="page" />
</template>

The change event now emits the native change event, not the new value, which is now emitted in the update:modelValue event:

<template>
- <USelectMenu v-model="country" :items="countries" @change="console.log(newVal)" />
+ <USelectMenu v-model="country" :items="countries" @update:modelValue="console.log(newVal)" />
</template>

This change affects the following components: Select, SelectMenu, RadioGroup.

The SelectMenu component searchable prop has been renamed to search-input and now defaults to true. To preserve v2 behavior (no search input):

<template>
- <USelectMenu :items="items" />
+ <USelectMenu :search-input="false" :items="items" />
</template>

The Accordion component has been redesigned. The multiple prop has been replaced by the type prop (defaults to single):

<template>
- <UAccordion multiple :items="items" />
+ <UAccordion type="multiple" :items="items" />
</template>

The Accordion component default-open prop and defaultOpen item property have been removed. State is now controlled using default-value (uncontrolled) or v-model (controlled):

<template>
- <UAccordion default-open multiple :items="items" />
+ <UAccordion
+   type="multiple"
+   :default-value="['0', '1']"
+   :items="items"
+ />
</template>

The Accordion component #item slot has been removed in favor of #content and #body:

<template>
- <template #item="{ item }">
-   {{ item.content }}
- </template>

+ <template #content="{ item }">
+   {{ item.content }}
+ </template>
</template>

The default slot now only customizes the trigger, with additional slots for finer control (#leading, #trailing, #body).

The Accordion component unmount prop has been renamed to unmount-on-hide and now defaults to true. To preserve v2 behavior (keep content mounted), use :unmount-on-hide="false":

<template>
- <UAccordion :items="items" />
+ <UAccordion :unmount-on-hide="false" :items="items" />
</template>

The Table component now uses TanStack Table under the hood. The rows prop has been renamed to data:

<template>
- <UTable :rows="rows" />
+ <UTable :data="data" />
</template>

The Table component columns definition is now explicit and semantic:

<script setup lang="ts">
const columns = [{
-  label: 'Status',
-  key: 'status'
+  header: 'Status',
+  accessorKey: 'status'
}]
</script>

The Table component row cell slot names have been changed from <column-accessorKey>-data to <column-accessorKey>-cell:

<template>
- <template #column-data="{ row }">
+ <template #column-cell="{ row }">
</template>

The Tabs component #item slot has been removed in favor of #content:

<template>
- <template #item="{ item }">
+ <template #content="{ item }">
</template>

The Tabs component default-index prop has been removed in favor of default-value:

<template>
- <UTabs :default-index="0" :items="tabs" />
+ <UTabs :default-value="0" :items="tabs" />
</template>

The Tabs component unmount prop has been renamed to unmount-on-hide and now defaults to true. To preserve v2 behavior where content stayed mounted:

<template>
- <UTabs :items="tabs" />
+ <UTabs :unmount-on-hide="false" :items="tabs" />
</template>

The Alert component close-button prop has been replaced by the close prop:

<template>
- <UAlert :close-button="{ icon: 'i-heroicons-x-mark', variant: 'link' }" />
+ <UAlert :close="{ icon: 'i-lucide-x', variant: 'link' }" />
</template>

The Alert component close event has been replaced by the update:open event:

<template>
- <UAlert @close="isOpen = false" />
+ <UAlert @update:open="isOpen = false" />
</template>

The Alert component #icon and #avatar slots have been replaced by a single #leading slot:

<template>
- <UAlert>
-   <template #icon>
-     <UIcon name="i-heroicons-command-line" />
-   </template>
- </UAlert>

+ <UAlert>
+   <template #leading>
+     <UIcon name="i-lucide-terminal" />
+   </template>
+ </UAlert>
</template>

The Form component now always validates on submit. The validate-on prop only controls which input events trigger validation. Pass an empty array to validate only on submit:

<template>
- <UForm :validate-on="['submit']" />
+ <UForm :validate-on="[]" />
</template>

Form components now use inline-flex instead of block layout, which means they no longer expand to full width by default. Add w-full manually with the class prop or configure it globally in your app.config.ts:

app.config.ts

export default defineAppConfig({
  ui: {
    input: { slots: { root: 'w-full' } },
    inputMenu: { slots: { root: 'w-full' } },
    textarea: { slots: { root: 'w-full' } },
    select: { slots: { base: 'w-full' } },
    selectMenu: { slots: { base: 'w-full' } }
  }
})

This change affects the following components: Input, InputMenu, Textarea, Select, SelectMenu.

The popper prop has been replaced by content for positioning:

<template>
- <UTooltip :popper="{ placement: 'top' }" />
+ <UTooltip :content="{ side: 'top' }" />

- <USelectMenu :popper="{ placement: 'bottom-start' }" />
+ <USelectMenu :content="{ side: 'bottom', align: 'start' }" />
</template>

This change affects the following components: Tooltip, Popover, DropdownMenu, ContextMenu, SelectMenu, InputMenu.

The Tooltip component shortcuts prop has been renamed to kbds and prevent to disabled:

<template>
- <UTooltip text="Open" :shortcuts="['⌘', 'O']" />
+ <UTooltip text="Open" :kbds="['meta', 'O']" />
</template>

The Popover component #panel slot has been renamed to #content:

<template>
  <UPopover>
    <UButton label="Open" />

-   <template #panel>
+   <template #content>
      <div class="p-4">Content</div>
    </template>
  </UPopover>
</template>

The ContextMenu component has been completely redesigned. It now uses items and has a proper trigger/content structure:

<template>
- <UContextMenu v-model="isOpen" :virtual-element="virtualElement" />
+ <UContextMenu :items="items">
+   <div>Right-click me</div>
+ </UContextMenu>
</template>

The Progress component value prop has been replaced by model-value and indicator by status:

<template>
- <UProgress :value="50" indicator />
+ <UProgress :model-value="50" status />
</template>

The Carousel component indicators prop has been renamed to dots:

<template>
- <UCarousel :items="items" indicators />
+ <UCarousel :items="items" dots />
</template>

The Carousel component now uses Embla Carousel under the hood.

The help prop/property has been renamed to description:

<template>
- <UCheckbox label="Remember me" help="Save my login details" />
+ <UCheckbox label="Remember me" description="Save my login details" />
</template>

<script setup lang="ts">
const items = [{
  label: 'Option 1',
- help: 'Description for option 1'
+ description: 'Description for option 1'
}]
</script>

This change affects the following components: Checkbox, RadioGroup.

The Breadcrumb component divider prop has been renamed to separator-icon and #divider slot to #separator:

<template>
- <UBreadcrumb :links="links" divider="i-lucide-arrow-right" />
+ <UBreadcrumb :items="items" separator-icon="i-lucide-arrow-right" />
</template>

The Avatar component chip props (chip-color, chip-position, chip-text) have been consolidated into a single chip prop:

<template>
- <UAvatar src="..." chip-color="green" chip-position="top-right" chip-text="" />
+ <UAvatar src="..." :chip="{ color: 'success', position: 'top-right' }" />
</template>

The Button component padded and truncate props have been removed. Use square instead of :padded="false":

<template>
- <UButton :padded="false" />
+ <UButton square />
</template>

The Chip component show prop is now a model (v-model:show):

<template>
- <UChip :show="isVisible" />
+ <UChip v-model:show="isVisible" />
</template>

The CommandPalette component groups prop structure has changed. Each group now has an items array and uses onSelect instead of click:

<script setup lang="ts">
const groups = [{
  id: 'actions',
  label: 'Actions',
- commands: [{ id: 'new', label: 'New file' }]
+ items: [{ id: 'new', label: 'New file' }]
}]
</script>

Changed composables

The useToast() composable timeout prop has been renamed to duration:

<script setup lang="ts">
const toast = useToast()

- toast.add({ title: 'Invitation sent', timeout: 0 })
+ toast.add({ title: 'Invitation sent', duration: 0 })
</script>

The useModal and useSlideover composables have been removed in favor of a more generic useOverlay composable:

Some important differences:

The useOverlay composable is now used to create overlay instances
Overlays that are opened, can be awaited for their result
Overlays can no longer be close using modal.close() or slideover.close(), rather, they close automatically: either when a close event is fired explicitly from the opened component OR when the overlay closes itself (clicking on backdrop, pressing the ESC key, etc)
To capture the return value in the parent component you must explicitly emit a close event with the desired value

<script setup lang="ts">
import { ModalExampleComponent } from '#components'

- const modal = useModal()
+ const overlay = useOverlay()

- modal.open(ModalExampleComponent)
+ const modal = overlay.create(ModalExampleComponent)
</script>

Props are now passed through a props attribute:

<script setup lang="ts">
import { ModalExampleComponent } from '#components'

- const modal = useModal()
+ const overlay = useOverlay()

const count = ref(0)

- modal.open(ModalExampleComponent, {
-   count: count.value
- })
+ const modal = overlay.create(ModalExampleComponent, {
+   props: {
+     count: count.value
+   }
+ })
</script>

Closing a modal is now done through the close event. The modal.open method now returns an instance that can be used to await for the result of the modal whenever the modal is closed:

<script setup lang="ts">
import { ModalExampleComponent } from '#components'

- const modal = useModal()
+ const overlay = useOverlay()

+ const modal = overlay.create(ModalExampleComponent)

- function openModal() {
-   modal.open(ModalExampleComponent, {
-     onSuccess() {
-       toast.add({ title: 'Success!' })
-     }
-   })
- }
+ async function openModal() {
+   const instance = modal.open(ModalExampleComponent, {
+     count: count.value
+   })
+
+   const result = await instance.result
+
+   if (result) {
+     toast.add({ title: 'Success!' })
+   }
+ }
</script>

Changed form validation

The error object property for targeting form fields has been renamed from path to name:

<script setup lang="ts">
function validate(state: any): FormError[] {
  const errors = []
  if (!state.email) {
    errors.push({
-     path: 'email',
+     name: 'email',
      message: 'Required'
    })
  }
  if (!state.password) {
    errors.push({
-     path: 'password',
+     name: 'password',
      message: 'Required'
    })
  }
  return errors
}
</script>

This page is a work in progress, we'll improve it regularly.