Skip to content

Nuxt UI

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 UButton and a newt/ui Button end 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.