1# Installation
2 
3## Nuxt Installation
4 
5```bash
6pnpm add @nuxt/ui
7```
8 
9```ts
10// nuxt.config.ts
11export default defineNuxtConfig({
12  modules: ['@nuxt/ui'],
13  css: ['~/assets/css/main.css']
14})
15```
16 
17```css
18/* assets/css/main.css */
19@import 'tailwindcss';
20@import '@nuxt/ui';
21```
22 
23**Critical**: Wrap app in UApp for Toast, Tooltip, and overlays to work:
24 
25```vue
26<!-- app.vue -->
27<template>
28  <UApp>
29    <NuxtPage />
30  </UApp>
31</template>
32```
33 
34### pnpm Gotcha
35 
36If using pnpm, either:
37 
381. Add `shamefully-hoist=true` to `.npmrc`, OR
392. Install tailwindcss explicitly: `pnpm add tailwindcss`
40 
41## Vue Installation (Vite)
42 
43```bash
44pnpm add @nuxt/ui
45```
46 
47```ts
48import ui from '@nuxt/ui/vite'
49import vue from '@vitejs/plugin-vue'
50// vite.config.ts
51import { defineConfig } from 'vite'
52 
53export default defineConfig({
54  plugins: [vue(), ui()]
55})
56```
57 
58```ts
59import ui from '@nuxt/ui/vue-plugin'
60// main.ts
61import { createApp } from 'vue'
62import App from './App.vue'
63import './assets/main.css'
64 
65const app = createApp(App)
66app.use(ui)
67app.mount('#app')
68```
69 
70```css
71/* assets/main.css */
72@import 'tailwindcss';
73@import '@nuxt/ui';
74```
75 
76**Critical**: Add `isolate` class to root for overlay stacking:
77 
78```vue
79<!-- App.vue -->
80<template>
81  <div class="isolate">
82    <UApp>
83      <RouterView />
84    </UApp>
85  </div>
86</template>
87```
88 
89### Auto-imports
90 
91Vue generates `auto-imports.d.ts` and `components.d.ts`. Add to `.gitignore`:
92 
93```gitignore
94auto-imports.d.ts
95components.d.ts
96```
97 
98## Module Options
99 
100```ts
101// nuxt.config.ts
102export default defineNuxtConfig({
103  modules: ['@nuxt/ui'],
104  ui: {
105    prefix: 'U', // Component prefix (default 'U')
106    fonts: true, // Enable @nuxt/fonts
107    colorMode: true, // Enable @nuxtjs/color-mode
108    theme: {
109      colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'],
110      transitions: true, // transition-colors on components
111      defaultVariants: {
112        color: 'primary',
113        size: 'md'
114      },
115      prefix: '' // Tailwind CSS prefix (v4.2+) - ensures prefixed utilities work
116    },
117    mdc: false, // Force Prose components
118    content: false, // Force UContent* components
119    experimental: {
120      componentDetection: false // Tree-shake unused components (v4.1+) - auto-generates CSS only for used components
121    }
122  }
123})
124```
125 
126## Vue Vite Options
127 
128```ts
129// vite.config.ts
130ui({
131  prefix: 'U',
132  colorMode: true,
133  inertia: true, // Inertia.js support
134  theme: {
135    colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'],
136    transitions: true,
137    defaultVariants: { color: 'primary', size: 'md' },
138    prefix: ''
139  },
140  ui: {
141    colors: { primary: 'green' }, // Runtime color config
142    button: { /* theme overrides */ }
143  }
144})
145```
146 
147## Auto-installed Modules
148 
149Nuxt UI automatically installs:
150 
151- `@nuxt/icon` - Icon system
152- `@nuxt/fonts` - Web fonts (if `fonts: true`)
153- `@nuxtjs/color-mode` - Dark mode (if `colorMode: true`)
154 
155## Common Issues
156 
157| Issue                     | Solution                                           |
158| ------------------------- | -------------------------------------------------- |
159| Tailwind not found (pnpm) | Add `shamefully-hoist=true` or install tailwindcss |
160| Overlays not showing      | Wrap app in `<UApp>`                               |
161| Vue overlays broken       | Add `isolate` class to root element                |
162| Icons not loading         | Check @nuxt/icon is installed                      |
163| Dark mode not working     | Ensure `colorMode: true` in config                 |
164 
165## Performance Features (v4.1+)
166 
167### Component Virtualization
168 
169Large datasets in CommandPalette, InputMenu, SelectMenu, Table, and Tree automatically use virtualization for better performance.
170 
171### Experimental Component Detection
172 
173Enable `experimental.componentDetection` to auto-generate CSS only for components you actually use:
174 
175```ts
176// nuxt.config.ts
177export default defineNuxtConfig({
178  ui: {
179    experimental: {
180      componentDetection: true
181    }
182  }
183})
184```
185 
186**Benefits:** Smaller CSS bundle, faster builds, reduced unused styles.
187 
188### Tailwind CSS Prefix Support (v4.2+)
189 
190Avoid style conflicts in complex apps:
191 
192```ts
193// nuxt.config.ts
194export default defineNuxtConfig({
195  ui: {
196    theme: {
197      prefix: 'ui-' // Prefixes all Tailwind utilities
198    }
199  }
200})
201```
202 
203**Result:** Components use `ui-bg-primary` instead of `bg-primary`.
204 
205## Best Practices
206 
207| Do                         | Don't                     |
208| -------------------------- | ------------------------- |
209| Wrap in UApp first         | Forget UApp wrapper       |
210| Use semantic colors        | Hardcode color values     |
211| Import CSS correctly       | Skip @nuxt/ui import      |
212| Check pnpm hoisting        | Ignore tailwindcss errors |
213| Use component detection    | Ship unused component CSS |
214| Use prefix in complex apps | Risk style conflicts      |
215