Nuxt UI 2.21.1 migration to v 3.0.0
I'm trying to migrate Nuxt Ui from version 2.21.1 to version 3.0.0, but I get some errors.
I'm running Nuxt 3.16 and my current implementation is
/app/assets/css/tailwind.css
56 Replies
Hi @EmanueleDB. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
I'll help you with migrating from Nuxt UI 2.21.1 to version 3.0.0. This is a significant upgrade that requires several changes to your implementation.
Key Changes for Nuxt UI v3 Migration
Nuxt UI v3 uses Tailwind CSS v4 which follows a CSS-first configuration approach. Here are the steps you need to take:
1. Update your package
First, install the Nuxt UI v3 package:
2. Update your CSS implementation
You need to modify your CSS approach. Instead of your current implementation, you should:
1. Create a main.css file that imports Tailwind and Nuxt UI
2. Use the new
@theme
directive for customization
Here's how your updated CSS file should look:
3. Update your Nuxt configuration
Make sure your nuxt.config.ts
includes the CSS file:
4. Remove tailwind.config.ts file
Nuxt UI v3 uses CSS-first theming, so you should remove your tailwind.config.ts file if you have one. The theme customization is now done through CSS variables in the @theme
directive as shown above.
5. Update UI component configurations
If you have any UI component customizations in your app.config.ts
, you'll need to update them as the structure has changed:
This replaces the older format where you might have had primary: 'green'
directly under the ui
key.
Common Issues
If you're encountering errors, they might be related to:
1. Dependency conflicts - check for version conflicts in your package.json
2. Component prop changes - many components have updated their props in v3
3. Tailwind configuration - the new CSS-first approach requires different configuration
For more detailed migration guidance, refer to the UI Pro Docs Migration guide which covers many of the same principles that apply to Nuxt UI.
Let me know what specific errors you're encountering for more targeted help.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@650262436557094954> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
in my nuxt.config.ts I have
and this is my tailwind.config.ts
If I follow the migration doc
https://ui.nuxt.com/getting-started/migration
I get an error here
also my file is called tailwind.css, does that need to be renamed in main.css?
@kapa.ai update you answer
Let me check the knowledge base for you again. One moment! :books:
----------------------
I'll provide an updated answer about migrating from Nuxt UI 2.21.1 to version 3.0.0 based on the knowledge sources.
Nuxt UI v3 Migration Guide
Nuxt UI v3 uses Tailwind CSS v4 which follows a CSS-first configuration approach. Here are the key steps for migration:
1. Install the Nuxt UI v3 package
2. Update your CSS implementation
Create a main.css file that imports Tailwind and Nuxt UI:
3. Update your Nuxt configuration
Make sure your
nuxt.config.ts
includes the CSS file:
4. Remove tailwind.config.ts file
As mentioned in the UI Pro Docs Migration guide:
- Delete the tailwind.config.ts
file
- Use the @theme
directive to apply your theme in the CSS file
- Use the @source
directive if you need Tailwind to detect classes in specific files
5. Check component usage
Many components may have updated their props or slots in v3. You should check the documentation for each component you're using to ensure compatibility.
This approach follows the CSS-first theming introduced in Nuxt UI v3, which is a significant change from the previous configuration-based approach in v2.
Let me know if you encounter specific errors during the migration process.
I hope this updated information helps with your migration to Nuxt UI v3!
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@650262436557094954> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
Cannot resolve file 'tailwindcss' in my main.css
you don't need any tailwind.config or tailwindcss options in nuxt.config in v4, just css, like
Where do I move the stuff that are inside the tailwind.config.ts?

make sure that related packages are installed
so these packages are now needed? They dont come from nuxt/ui anymore?
IDK, I use setup from tailwindcss v4
https://tailwindcss.com/docs/installation/framework-guides/nuxt
Install Tailwind CSS with Nuxt
Setting up Tailwind CSS in a Nuxt project.
yes I saw that but in nuxt/ui everything should be already installed as dependency
otherwise we have double dependency
where do I put stuff like
in css using variables and related rules
[ nuxi 11:13:11 AM] ERROR Cannot restart nuxt: It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install @tailwindcss/postcss and update your PostCSS configuration.
had this happen to me too, might be due to a module that uses tailwind3 (for example nuxtui 2)
I made it working at the end, but I reverted everything to 2.21.1. Nuxt UI 3.0 is a completly new UI, you have to destroy the entire logic for the UTable and adapt it to the new structure. It's not a update, it's a completly new UI with different rules
Hi do you have an example of main.css for tailwind version 4? I can't find anything in the official doc
Nuxt UI
Migration - Nuxt UI v3
A comprehensive guide to migrate your application from Nuxt UI v2 to Nuxt UI v3.
but i have same problem
I kinda of fixed it
how?
what problem do you have?
I have problems with the custom colors, ho do you define them and pass them to a UButton?
it accepts just those default 7
ok i got it, you pass it inside the class and you dont pass the color prop
@EmanueleDB Are you not using Nuxt UI v3?
yes
like this works
also with my custom colors
if I pass it in the color prop it doesn't work
Did you resolve this? ERROR Cannot restart nuxt: It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install @tailwindcss/postcss and update your PostCSS configuration.
I followed the config and I dont have that error
have you installed tailwindcss @tailwindcss/vite
?
Yes, but seems to be causing all the issues
nuxt.config.ts
css: ['~/assets/css/main.css'],
and in the main.css at the top
@import 'tailwindcss' theme(static);
@import '@nuxt/ui';
Yeah I've done all these and it still is asking for postcss
delete the node modules and the pnpm.lock and reinstall the deps
FYI the colors must be defined like this in the main.css to be compatible with the Nuxt UI 3 color prop
and this in app.config.ts
Okay, I didn't redo the colours like that. I will try getting Nuxt UI 3 with TW4 this weekend
I'm updating all the components and I'm getting crazy, the doc is very bad
I ended up removing the UTable and I made it by myself with the same style and feature, now I have control over the row and the columns
Maybe this comment helps here too:
https://discord.com/channels/473401852243869706/897487139888062506/1351537377402687509
It doesn't redirect me to the correct comment I guess, there is a github error
I kind of finished the porting today, I hope I didn't forget anything but I will check it again. If you use vue-tsc you will see 58 ts error logged and there is already a GitHub issue opened. I hope they solve it asap because I run vue-tsc in the pipelines before deploying
It's not a Github comment, it's a Discord message from earlier today

Eh discord from mobile sucks
--color- wont work with nuxt ui 3
They use --ui-
So you have to map colors and the style you want to add or overwrite with --ui-
--color are Tailwind's colors on the screen, we override Tailwind's green
correct but if you want to pass a color in the nuxt ui components in the props
color
like UButton etc you need to list the --ui-primary to overwrite itYou might have moved on from this, but you can still use your
tailwind.config.js
file in Tailwind CSS v4 using the @config
directive until you migrate to a CSS-based config. It is documented in the upgrade guide.Upgrade guide - Getting started
Upgrading your Tailwind CSS projects from v3 to v4.
Thanks but I moved everything in my main.css. It's confusing because we should follow the Nuxt UI migration doc that is not even mentioning the vite plugin that the tailwind doc instead suggest to install.
I made it working at the end, there is a big problem when running vue-tsc and that is scary if you have vue-tsc running in the pipelines, because it throws 58 errors right now
It doesn't mention the plugin because everything is managed by NuxtUI so you don't have to worry about the plugin or installation
If you dont install the plugin it doesn't work. That was I though as well when I saw the update doc, but it doesn't work without that plugin
@EmanueleDB You can create an exit with a reproduction because it should work just fine without installing the plugin ?
you get this error without the plugin @HugoRCD
Maybe it works for new projects, I migrated from Nuxt Ui 2.21.1, I haven't tried to make a new project. I'm going to deploy my app in a few weeks and yesterday was a rough day updating everything, it is scary refactor everything just a few days before going public
Tomorrow when I'm in front of my project I will try to remove it but here I dont see either to install tailwindcss, on the tailwind doc, about nuxt, it says to install those packages. I think I could remove the plugin but I still need tailwindcss in my dependencies.
@HugoRCD I can confirm that the plugin is not needed, just the tailwindcss installed in the dependencies.
I downgrade vue-tsc to 2.2.0 as suggested here https://github.com/nuxt/ui/issues/3405
GitHub
type errors on slots with vue-tsc 2.2.4 · Issue #3405 · nuxt/ui
Environment node: 22 nuxt: 3.15.4 Is this bug related to Nuxt or Vue? Nuxt Version v3.0.0-alpha.13 Reproduction not required Description run "npx nuxi typecheck" Argument of type '{ i...
I'm still confused about the colors. I mapped them like this in my main.css
and in my app.config.ts
to be able to use them like this
IS this the correct way?
they are correctly mapped in the root colors of tailwind, and they can be used everywhere not in the nuxt ui components like this
bg-[var(--ui-expired)]

No, that's not the way to do it. You have to add your color in the
nuxt.config.ts
and in the app.config.ts
and you can declare the shades of your color in your main.css file.
https://ui.nuxt.com/getting-started/theme#colorsNuxt UI
Theme - Nuxt UI v3
Learn how to customize Nuxt UI components using Tailwind CSS v4, CSS variables and the Tailwind Variants API for powerful and flexible theming.
Doing it like this the colors will be recognised also by the Nuxt Ui components?
my colors are listed also in the nuxt.config.ts
ui: {
theme: {
colors: [
'primary',
'secondary',
'tertiary',
'info',
'success',
'warning',
'error',
'active',
'notRequested',
'requested',
'expired',
'cancelled',
'scheduled'
]
}
},
but I dont need all the shades 50,100, etc
I made this in my main.css
what do i still need to do in app.config.ts?
there are no example with custom colors in this doc https://ui.nuxt.com/getting-started/theme
Nuxt UI
Theme - Nuxt UI v3
Learn how to customize Nuxt UI components using Tailwind CSS v4, CSS variables and the Tailwind Variants API for powerful and flexible theming.
I dont want to use primary, secondary etc, I want to use active in my Nuxt UI components
nuxt ui map --ui-active

my color is in the root colors of tailwind but its not working in the components

I tried to move app.config.ts in /app folder (im using compatibility version 4) and it still doesn't work
I believe I'm obliged to overwrite the primary, secondary, etc to make it working with the nuxt ui components
ok I made it working finally.
Thanks @HugoRCD . I would an example also with a custom color in the doc and specify that app.config.ts needs to be in the /app folder when running compatibility version 4
Yes, maybe we should improve the example to add a custom color 🤔 However, it does say that the
app.config.ts
must be in the /app
folder.
https://nuxt.com/docs/getting-started/upgrade#new-directory-structureYes in the nuxt doc it does, but a little reminder also in the nuxt ui doc wouldn't be bad. Yes I believe examples are the best way and people, like me, understand better
We'll see in the future, since for the moment the new structure has not been officially released, I don't think it belongs in the NuxtUI doc.