Customising the Nuxt UI theme
Change a token, replace one component's overrides, or use the theme in a Vue project without Nuxt.
The theme is a file in your project, so there is no configuration surface between you and it. These are the three changes people make.
Change a token
This is the first thing to reach for, because it changes newt/ui and Nuxt UI
together and it survives the next add:
:root {
--newt-brand: #7a5af8;
--newt-brand-hover: #6b4ce0;
--newt-brand-active: #5a3fc0;
}
UButton, a newt/ui Button, focus rings and the highlighted row of every
menu all move. See Theming for the full list of tokens.
Change one component
newtNuxtUi is a plain object in the shape Nuxt UI’s app.config.ts takes.
Spread it and replace the key you want:
import { newtNuxtUi } from "~/lib/nuxt-ui"
export default defineAppConfig({
ui: {
...newtNuxtUi,
// Keep Nuxt UI's own switch colour instead of green.
switch: { slots: newtNuxtUi.switch.slots },
// Theme a component the file does not cover.
tabs: { slots: { list: "bg-(--newt-bg-base)" } },
},
})
To change the theme for good, edit app/lib/nuxt-ui.ts itself. The classes in
it are Tailwind utilities that read tokens through Tailwind 4’s
bg-(--newt-bg-floating) form; Nuxt UI’s
theme reference
lists each component’s slots and variants.
Use it without Nuxt
Nuxt UI also runs in a plain Vite and Vue project, and so does the theme. The
object goes to the Vite plugin instead of app.config.ts:
import ui from "@nuxt/ui/vite"
import vue from "@vitejs/plugin-vue"
import { defineConfig } from "vite"
import { newtNuxtUi } from "./src/lib/nuxt-ui"
export default defineConfig({
plugins: [vue(), ui({ ui: newtNuxtUi })],
})
Without the colour mode module there is nothing to set data-newt-theme, so
set it yourself beside the class: <html class="light" data-newt-theme="light">.
What it does not do
- It themes Nuxt UI; it does not replace it. A
UButtonand a newt/uiButtonend up looking alike, but they are still two components with two APIs. Use Nuxt UI for what newt/ui does not have, not for both. - Components the file does not name are recoloured by the variables and keep Nuxt UI’s own shapes and spacing. The dashboard, page, chat and editor families are in that group.
- Nuxt UI’s colour utilities with opacity, such as a subtle badge’s tinted background, are computed from the token and so follow it, but they were tuned for Nuxt UI’s palette. Check the few you rely on in both palettes.
- It was written and checked against Nuxt UI 4.12. A later major may rename slots, and an override for a slot that no longer exists is ignored without an error.