ui/docs/content/1.getting-started/2.migration.md

---
title: Migration
description: 'A comprehensive guide to migrate your application from Nuxt UI v2 to Nuxt UI v3.'
---

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

::steps

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

::note{to="https://tailwindcss.com/docs/upgrade-guide#changes-from-v3" target="_blank"}
For a detailed walkthrough of all changes, refer to the official **Tailwind CSS v4 upgrade guide**.
::

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

::code-group

```css [app/assets/css/main.css]
@import "tailwindcss" theme(static);
```

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

::

2. Run the Tailwind CSS upgrade tool:

```bash
npx @tailwindcss/upgrade
```

### Update Nuxt UI

3. Install the latest version of the package:

::module-only
#ui
:::div

::::code-group{sync="pm"}

```bash [pnpm]
pnpm add @nuxt/ui@next
```

```bash [yarn]
yarn add @nuxt/ui@next
```

```bash [npm]
npm install @nuxt/ui@next
```

```bash [bun]
bun add @nuxt/ui@next
```

::::

:::

#ui-pro
:::div

::::code-group{sync="pm"}

```bash [pnpm]
pnpm add @nuxt/ui-pro@next
```

```bash [yarn]
yarn add @nuxt/ui-pro@next
```

```bash [npm]
npm install @nuxt/ui-pro@next
```

```bash [bun]
bun add @nuxt/ui-pro@next
```

::::

:::

::

4. Import it in your CSS:

::module-only
#ui
:::div

```css [app/assets/css/main.css]{2}
@import "tailwindcss" theme(static);
@import "@nuxt/ui";
```

:::

#ui-pro
:::div

```css [app/assets/css/main.css]{2}
@import "tailwindcss" theme(static);
@import "@nuxt/ui-pro";
```

:::
::

::module-only
#ui

:::div
5. Wrap you app with the [App](/components/app) component:
:::

#ui-pro
:::div
5. Add the `@nuxt/ui-pro` module in your `nuxt.config.ts` file as it's no longer a layer:

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

6. Wrap you app with the [App](/components/app) component:
:::

::

```vue [app.vue] {2,4}
<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](/getting-started/theme#design-system) with 7 color aliases:

| Color | Default | Description |
| --- | --- | --- |
| `primary`{color="primary"} | `green` | Main brand color, used as the default color for components. |
| `secondary`{color="secondary"} | `blue` | Secondary color to complement the primary color. |
| `success`{color="success"} | `green` | Used for success states. |
| `info`{color="info"} | `blue` | Used for informational states. |
| `warning`{color="warning"} | `yellow` | Used for warning states. |
| `error`{color="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:

1. The `gray` color has been renamed to `neutral`

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

::note
You can also use the new [design tokens](/getting-started/theme#neutral-palette) to handle light and dark mode:

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

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

2. The `DEFAULT` shade that let you write `text-primary` no longer exists, you can use [color shades](/getting-started/theme#color-shades) instead:

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

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

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

::note{to="/getting-started/theme#colors"}
Learn how to extend the design system to add new color aliases.
::

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

```diff
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](/getting-started/theme#components-theme), which makes all the overrides you made using the `app.config.ts` and the `ui` prop obsolete.

1. Update your [`app.config.ts`](/getting-started/theme#config) to override components with their new theme:

```diff
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](/getting-started/theme#props) to override each component's slots using their new theme:

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

::tip{to="/components/button#theme"}
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 components to align with the Reka UI naming convention.

| v2 | v3 |
| --- | --- |
| `Divider` | `Separator` |
| `Dropdown` | `DropdownMenu` |
| `FormGroup` | `FormField` |
| `Range` | `Slider` |
| `Toggle` | `Switch` |
| `Notification` | `Toast` |
| `VerticalNavigation` | `NavigationMenu` with `orientation="vertical"` |
| `HorizontalNavigation` | `NavigationMenu` with `orientation="horizontal"` |

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

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

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

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

---

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