Migration to v4
Nuxt UI v4.0 represents a major milestone where Nuxt UI Pro has been merged into the main Nuxt UI package. This means all Pro components and features are now available in the open-source @nuxt/ui
package.
This guide provides step-by-step instructions to migrate your application from v3 to v4.
Migrate your project
Update dependencies
Replace Nuxt UI Pro with Nuxt UI:
If you were using @nuxt/ui-pro
, replace it with @nuxt/ui
:
pnpm remove @nuxt/ui-pro
pnpm add @nuxt/ui@latest
yarn remove @nuxt/ui-pro
yarn add @nuxt/ui@latest
npm uninstall @nuxt/ui-pro
npm install @nuxt/ui@latest
bun remove @nuxt/ui-pro
bun add @nuxt/ui@latest
If you were already using @nuxt/ui
v3, simply update to v4:
pnpm add @nuxt/ui@latest
yarn add @nuxt/ui@latest
npm install @nuxt/ui@latest
bun add @nuxt/ui@latest
Update configuration
Replace @nuxt/ui-pro
with @nuxt/ui
in your modules:
export default defineNuxtConfig({
modules: [
- '@nuxt/ui-pro',
+ '@nuxt/ui'
]
})
Update the import in your vite.config.ts
:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
- import uiPro from '@nuxt/ui-pro/vite'
+ import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
- uiPro({
+ ui({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
}
}
})
]
})
Move component theming configuration:
If you had custom component theming in the uiPro
key, move it to the ui
key:
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
},
- },
- uiPro: {
- pageCard: {
- slots: {
- root: 'rounded-xl',
- }
- }
+ pageCard: {
+ slots: {
+ root: 'rounded-xl',
+ }
+ }
}
})
]
})
Update your CSS imports:
If you were importing @nuxt/ui-pro
styles, replace with @nuxt/ui
:
@import "tailwindcss";
- @import "@nuxt/ui-pro";
+ @import "@nuxt/ui";
Update CSS imports:
Update your CSS file:
@import "tailwindcss";
- @import "@nuxt/ui-pro";
+ @import "@nuxt/ui";
Changes from v3
Now that you have updated your project dependencies, you need to address the breaking changes in Nuxt UI v4.
Merged Pro components
All Nuxt UI Pro components are now available in the main @nuxt/ui
package. You can continue using them exactly as before, but they're now imported from @nuxt/ui
instead of @nuxt/ui-pro
.
- import { PageHero, PageSection } from '@nuxt/ui-pro'
+ import type { BannerProps } from '@nuxt/ui'
Renamed components
Several components have been renamed for better consistency:
v3 | v4 |
---|---|
ButtonGroup | FieldGroup |
PageMarquee | Marquee |
Removed components
Some components have been removed in favor of more standard alternatives:
v3 | v4 |
---|---|
PageAccordion | Accordion |
<template>
- <UPageAccordion :items="faqItems" />
+ <UAccordion :items="items" :unmount-on-hide="false" :ui="{ trigger: 'text-base', body: 'text-base text-muted' }" />
</template>
AI SDK v5 migration (Optional)
ChatMessage
, ChatMessages
, ChatPrompt
, ChatPromptSubmit
, ChatPalette
). If you're not using AI features, you can skip this section.First, update your ai
dependency:
// package.json
{
"dependencies": {
- "ai": "^4.x.x"
+ "ai": "^5.x.x"
}
}
Chat components have been updated to work with AI SDK v5 too. The main changes are:
useChat
→ Chat
class
The useChat
composable has been replaced with the new Chat
class:
<script setup lang="ts">
- import { useChat } from '@ai-sdk/vue'
+ import { Chat } from '@ai-sdk/vue'
+ import type { UIMessage } from 'ai'
- const { messages, input, handleSubmit, status, error, reload, setMessages } = useChat()
+ const messages: UIMessage[] = []
+ const input = ref('')
+
+ const chat = new Chat({
+ messages
+ })
+
+ function handleSubmit(e: Event) {
+ e.preventDefault()
+ chat.sendMessage({ text: input.value })
+ input.value = ''
+ }
</script>
Message format: content
→ parts
Messages now use the parts
format instead of content
:
// When manually creating messages
- setMessages([{
+ messages.push({
id: '1',
role: 'user',
- content: 'Hello world'
+ parts: [{ type: 'text', text: 'Hello world' }]
- }])
+ })
// In templates
<template>
- <UChatMessage :content="message.content" />
+ <UChatMessage :parts="message.parts" />
</template>
Method changes
Some methods have been renamed:
// Regenerate the last message
- reload()
+ chat.regenerate()
// Access chat state
- :messages="messages"
- :status="status"
+ :messages="chat.messages"
+ :status="chat.status"
New getTextFromMessage
utility
Nuxt UI provides a new utility to extract text from AI SDK v5 message parts:
<script setup lang="ts">
import { getTextFromMessage } from '@nuxt/ui/utils/ai'
</script>
<template>
<UChatMessages :messages="chat.messages" :status="chat.status">
<template #content="{ message }">
<!-- Extract text from message parts and render with MDC -->
<MDC :value="getTextFromMessage(message)" :cache-key="message.id" unwrap="p" />
</template>
</UChatMessages>
</template>
This utility safely extracts text content from the parts
array of AI SDK v5 messages.
For more details on AI SDK v5 changes, review the official AI SDK v5 migration guide.