1# Conventions
2 
3Coding patterns specific to Nuxt UI.
4 
5## Auto-registered modules
6 
7Nuxt UI automatically registers `@nuxt/icon`, `@nuxt/fonts`, and `@nuxtjs/color-mode`. Do **not** add them to your `modules` array. Configure them via root-level keys in `nuxt.config.ts`:
8 
9```ts
10// nuxt.config.ts
11export default defineNuxtConfig({
12  modules: ['@nuxt/ui'],
13  icon: { /* @nuxt/icon options */ },
14  fonts: { /* @nuxt/fonts options */ },
15  colorMode: { /* @nuxtjs/color-mode options */ }
16})
17```
18 
19Disable any of them: `ui: { fonts: false }`, `ui: { colorMode: false }`.
20 
21## Content module integration
22 
23When using `@nuxt/content`, it **must** come after `@nuxt/ui` in the `modules` array — otherwise prose components won't be available:
24 
25```ts
26// nuxt.config.ts
27export default defineNuxtConfig({
28  modules: ['@nuxt/ui', '@nuxt/content']
29})
30```
31 
32Add `@source` in your CSS so Tailwind generates classes used in markdown/MDC:
33 
34```css
35/* app/assets/css/main.css */
36@import "tailwindcss";
37@import "@nuxt/ui";
38 
39@source "../../../content/**/*";
40```
41 
42Use `mapContentNavigation` to transform content navigation for components like `UBreadcrumb`:
43 
44```ts
45import { mapContentNavigation } from '@nuxt/ui/utils/content'
46import { findPageBreadcrumb } from '@nuxt/content/utils'
47 
48const breadcrumb = computed(() =>
49  mapContentNavigation(findPageBreadcrumb(navigation.value, page.value?.path))
50)
51```
52 
53## IDE setup
54 
55Recommended `.vscode/settings.json` for Tailwind IntelliSense autocomplete with Nuxt UI:
56 
57```json
58{
59  "files.associations": { "*.css": "tailwindcss" },
60  "editor.quickSuggestions": { "strings": "on" },
61  "tailwindCSS.classAttributes": ["class", "ui"],
62  "tailwindCSS.classFunctions": ["defineAppConfig"]
63}
64```
65 
66## UApp wrapper
67 
68Always wrap your app in `UApp` — it provides:
69- Toast container (`useToast`)
70- Tooltip provider
71- Programmatic overlay context (`useOverlay`)
72- i18n locale support
73 
74```vue
75<UApp :locale="fr">
76  <NuxtPage /> <!-- or <RouterView /> for Vue -->
77</UApp>
78```
79 
80## Icons
81 
82Nuxt UI registers `@nuxt/icon` automatically. Format: `i-{collection}-{name}`. Prefer `lucide` collection.
83 
84```vue
85<UIcon name="i-lucide-sun" class="size-5" />
86<UButton icon="i-lucide-plus" label="Add" />
87<UAlert icon="i-lucide-info" title="Heads up" />
88```
89 
90Install collections locally for reliable SSR and best performance:
91 
92```bash
93pnpm i @iconify-json/lucide
94pnpm i @iconify-json/simple-icons
95```
96 
97Custom local collections (Nuxt only):
98 
99```ts
100// nuxt.config.ts
101export default defineNuxtConfig({
102  icon: {
103    customCollections: [{
104      prefix: 'custom',
105      dir: './app/assets/icons'
106    }]
107  }
108})
109```
110 
111### Default icon overrides
112 
113Components like `Modal`, `Select`, `Accordion`, etc. use default icons from `appConfig.ui.icons`. Override them globally:
114 
115```ts
116// app.config.ts
117export default defineAppConfig({
118  ui: {
119    icons: {
120      loading: 'i-lucide-refresh-cw',
121      close: 'i-lucide-x',
122      check: 'i-lucide-check',
123      chevronDown: 'i-lucide-chevron-down',
124      chevronRight: 'i-lucide-chevron-right',
125      arrowLeft: 'i-lucide-arrow-left',
126      arrowRight: 'i-lucide-arrow-right'
127    }
128  }
129})
130```
131 
132## Slot patterns
133 
134Most components follow consistent slot naming:
135 
136| Slot | Used by | Purpose |
137|---|---|---|
138| `#header` | Card, Modal, Slideover, DashboardPanel | Top section |
139| `#body` | DashboardPanel | Scrollable content area |
140| `#footer` | Card, Modal, Slideover, DashboardPanel | Bottom section |
141| `#left` | Page, DashboardNavbar | Left sidebar or content |
142| `#right` | Page, DashboardNavbar, Header | Right sidebar or content |
143| `#leading` | Input, Button, Alert | Before main content (icon area) |
144| `#trailing` | Input, Button | After main content (icon area) |
145| `#content` | Modal, Slideover, Popover, Tooltip | Full content override |
146| `#default` | Most components | Main content area |
147 
148## Items arrays
149 
150Many components accept an `items` prop. Two patterns:
151 
152**Flat array** — plain list:
153 
154```ts
155const items = [
156  { label: 'Edit', icon: 'i-lucide-pencil' },
157  { label: 'Delete', icon: 'i-lucide-trash', color: 'error' }
158]
159```
160 
161**Nested array** — groups with automatic separators between them:
162 
163```ts
164const items = [
165  [
166    { label: 'Edit', icon: 'i-lucide-pencil' },
167    { label: 'Duplicate', icon: 'i-lucide-copy' }
168  ],
169  [
170    { label: 'Delete', icon: 'i-lucide-trash', color: 'error' }
171  ]
172]
173```
174 
175Components supporting nested arrays: `UDropdownMenu`, `UContextMenu`, `UCommandPalette`, `UNavigationMenu`.
176 
177## Composables
178 
179### useToast
180 
181```ts
182const toast = useToast()
183 
184toast.add({
185  title: 'Success',
186  description: 'Item saved',
187  color: 'success',
188  icon: 'i-lucide-check-circle',
189  duration: 5000,
190  actions: [{ label: 'Undo', onClick: () => {} }]
191})
192 
193toast.remove('toast-id')
194toast.clear()
195```
196 
197### useOverlay
198 
199Programmatic modals, slideovers, drawers — no template `v-model` needed. See [overlays recipe](../recipes/overlays.md) for full patterns.
200 
201```ts
202const overlay = useOverlay()
203const modal = overlay.create(MyComponent)
204const instance = modal.open({ title: 'Confirm?' })
205if (await instance.result) { /* confirmed */ }
206```
207 
208### defineShortcuts
209 
210```ts
211defineShortcuts({
212  meta_k: () => openSearch(),
213  escape: () => close(),
214  meta_enter: {
215    handler: () => submit(),
216    whenever: [isFormValid]
217  }
218})
219```
220 
221Keys: `meta` (Cmd/Ctrl), `ctrl`, `alt`, `shift`. Separator: `_`.
222 
223### extractShortcuts
224 
225Wire up keyboard shortcuts from menu items:
226 
227```ts
228const items = [
229  { label: 'New file', kbds: ['meta', 'n'], onSelect: () => newFile() },
230  { label: 'Save', kbds: ['meta', 's'], onSelect: () => save() }
231]
232 
233defineShortcuts(extractShortcuts(items))
234```
235 
236### Internationalization (i18n)
237 
238Nuxt UI supports 50+ locales. Set the locale on `UApp` — all components inherit it.
239 
240#### Static locale
241 
242```vue
243<script setup lang="ts">
244import { fr } from '@nuxt/ui/locale'
245</script>
246 
247<template>
248  <UApp :locale="fr">
249    <NuxtPage />
250  </UApp>
251</template>
252```
253 
254#### Extend a built-in locale
255 
256`extendLocale` is auto-imported. Override specific messages or the `code` (affects date/time formatting in Calendar, InputDate, InputTime):
257 
258```ts
259import { en } from '@nuxt/ui/locale'
260 
261const locale = extendLocale(en, {
262  code: 'en-AU',
263  messages: {
264    commandPalette: { placeholder: 'Search a component...' }
265  }
266})
267```
268 
269#### Custom locale from scratch
270 
271```ts
272import type { Messages } from '@nuxt/ui'
273 
274const locale = defineLocale<Messages>({
275  name: 'My locale',
276  code: 'en',
277  dir: 'ltr',
278  messages: {
279    // all component message keys
280  }
281})
282```
283 
284#### Dynamic locale with @nuxtjs/i18n
285 
286```ts
287// nuxt.config.ts
288export default defineNuxtConfig({
289  modules: ['@nuxt/ui', '@nuxtjs/i18n'],
290  i18n: {
291    locales: [
292      { code: 'en', name: 'English' },
293      { code: 'fr', name: 'Français' },
294      { code: 'ar', name: 'العربية' }
295    ]
296  }
297})
298```
299 
300```vue
301<script setup lang="ts">
302import * as locales from '@nuxt/ui/locale'
303 
304const { locale } = useI18n()
305 
306const lang = computed(() => locales[locale.value]?.code)
307const dir = computed(() => locales[locale.value]?.dir)
308 
309useHead({
310  htmlAttrs: { lang, dir }
311})
312</script>
313 
314<template>
315  <UApp :locale="locales[locale]">
316    <NuxtPage />
317  </UApp>
318</template>
319```
320 
321Each locale has a `dir` property (`'ltr'` or `'rtl'`). `UApp` uses it to set directionality on all components. Use `useHead` to propagate `lang` and `dir` to the `<html>` element.
322 
323## Color mode
324 
325Nuxt UI registers `@nuxtjs/color-mode` automatically. Built-in components for switching:
326- `UColorModeButton` — single button toggle (light/dark)
327- `UColorModeSwitch` — toggle switch
328- `UColorModeSelect` — dropdown with system/light/dark options
329- `UColorModeAvatar` — displays different avatar per mode
330- `UColorModeImage` — displays different image per mode
331 
332For custom color mode UI, use `useColorMode` with `ClientOnly` to avoid hydration mismatch:
333 
334```vue
335<script setup lang="ts">
336const colorMode = useColorMode()
337 
338const isDark = computed({
339  get: () => colorMode.value === 'dark',
340  set: (v) => { colorMode.preference = v ? 'dark' : 'light' }
341})
342</script>
343 
344<template>
345  <ClientOnly>
346    <USwitch v-model="isDark" />
347    <template #fallback>
348      <div class="size-8" />
349    </template>
350  </ClientOnly>
351</template>
352```
353 
354## Official templates
355 
356Bootstrap a project from a template instead of starting from scratch:
357 
358```bash
359npx nuxi@latest init -t ui              # Starter
360npx nuxi@latest init -t ui/dashboard    # Dashboard
361npx nuxi@latest init -t ui/docs         # Docs (Nuxt Content)
362npx nuxi@latest init -t ui/landing      # Landing page
363npx nuxi@latest init -t ui/saas         # SaaS (landing + pricing + docs + blog)
364npx nuxi@latest init -t ui/chat         # AI chat (Vercel AI SDK)
365npx nuxi@latest init -t ui/editor       # Rich text editor
366npx nuxi@latest init -t ui/portfolio    # Portfolio
367npx nuxi@latest init -t ui/changelog    # Changelog
368```
369 
370## Responsive patterns
371 
372- Dashboard sidebar hides on mobile, shows a slideover/drawer via `UDashboardSidebar` `mode` prop
373- `UHeader` body slot is the mobile menu content (shown when hamburger is tapped)
374- Most components handle responsiveness automatically — avoid manual breakpoint classes unless needed
375- Use `UPageAside` for sidebars that should hide below `lg` breakpoint
376