Migration

Nuxt UI v3.0 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

@import "tailwindcss" theme(static);

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

npx @tailwindcss/upgrade

pnpm add @nuxt/ui@next

yarn add @nuxt/ui@next

npm install @nuxt/ui@next

bun add @nuxt/ui@next

pnpm add @nuxt/ui-pro@next

yarn add @nuxt/ui-pro@next

npm install @nuxt/ui-pro@next

bun add @nuxt/ui-pro@next

@import "tailwindcss" theme(static);
@import "@nuxt/ui";

@import "tailwindcss" theme(static);
@import "@nuxt/ui-pro";

export default defineNuxtConfig({
-  extends: ['@nuxt/ui-pro'],
-  modules: ['@nuxt/ui']
+  modules: ['@nuxt/ui-pro']
})

<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:

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

1. 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>

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

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

2. The DEFAULT shade that let you write text-primary no longer exists, you can use color shades instead:

<template>
-  <p class="text-primary">Hello</p>
+  <p class="text-(--ui-primary)">Hello</p>
</template>

3. 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" />

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

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

5. 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.

1. 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'
+       }
     }
   }
})

2. 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>

Renamed components

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

Changed components

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

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

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

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