Installation

Nuxt Installation

pnpm add @nuxt/ui

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

/* assets/css/main.css */
@import 'tailwindcss';
@import '@nuxt/ui';

Critical: Wrap app in UApp for Toast, Tooltip, and overlays to work:

<!-- app.vue -->
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

pnpm Gotcha

If using pnpm, either:

1. Add shamefully-hoist=true to .npmrc, OR
2. Install tailwindcss explicitly: pnpm add tailwindcss

Vue Installation (Vite)

pnpm add @nuxt/ui

import ui from '@nuxt/ui/vite'
import vue from '@vitejs/plugin-vue'
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue(), ui()]
})

import ui from '@nuxt/ui/vue-plugin'
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import './assets/main.css'

const app = createApp(App)
app.use(ui)
app.mount('#app')

/* assets/main.css */
@import 'tailwindcss';
@import '@nuxt/ui';

Critical: Add isolate class to root for overlay stacking:

<!-- App.vue -->
<template>
  <div class="isolate">
    <UApp>
      <RouterView />
    </UApp>
  </div>
</template>

Auto-imports

Vue generates auto-imports.d.ts and components.d.ts. Add to .gitignore:

auto-imports.d.ts
components.d.ts

Module Options

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    prefix: 'U', // Component prefix (default 'U')
    fonts: true, // Enable @nuxt/fonts
    colorMode: true, // Enable @nuxtjs/color-mode
    theme: {
      colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'],
      transitions: true, // transition-colors on components
      defaultVariants: {
        color: 'primary',
        size: 'md'
      },
      prefix: '' // Tailwind CSS prefix (v4.2+) - ensures prefixed utilities work
    },
    mdc: false, // Force Prose components
    content: false, // Force UContent* components
    experimental: {
      componentDetection: false // Tree-shake unused components (v4.1+) - auto-generates CSS only for used components
    }
  }
})

Vue Vite Options

// vite.config.ts
ui({
  prefix: 'U',
  colorMode: true,
  inertia: true, // Inertia.js support
  theme: {
    colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'],
    transitions: true,
    defaultVariants: { color: 'primary', size: 'md' },
    prefix: ''
  },
  ui: {
    colors: { primary: 'green' }, // Runtime color config
    button: { /* theme overrides */ }
  }
})

Auto-installed Modules

Nuxt UI automatically installs:

• @nuxt/icon - Icon system
• @nuxt/fonts - Web fonts (if fonts: true)
• @nuxtjs/color-mode - Dark mode (if colorMode: true)

Common Issues

Performance Features (v4.1+)

Component Virtualization

Large datasets in CommandPalette, InputMenu, SelectMenu, Table, and Tree automatically use virtualization for better performance.

Experimental Component Detection

Enable experimental.componentDetection to auto-generate CSS only for components you actually use:

// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    experimental: {
      componentDetection: true
    }
  }
})

Benefits: Smaller CSS bundle, faster builds, reduced unused styles.

Tailwind CSS Prefix Support (v4.2+)

Avoid style conflicts in complex apps:

// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'ui-' // Prefixes all Tailwind utilities
    }
  }
})

Result: Components use ui-bg-primary instead of bg-primary.

Best Practices