create-wervt 0.2.14 → 0.2.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/index.js +2 -0
- package/package.json +2 -2
- package/template/.claude/skills/nuxt-ui/SKILL.md +85 -243
- package/template/.claude/skills/nuxt-ui/references/components.md +184 -313
- package/template/.claude/skills/nuxt-ui/references/guidelines/component-selection.md +124 -0
- package/template/.claude/skills/nuxt-ui/references/guidelines/conventions.md +372 -0
- package/template/.claude/skills/nuxt-ui/references/guidelines/design-system.md +378 -0
- package/template/.claude/skills/nuxt-ui/references/guidelines/forms.md +235 -0
- package/template/.claude/skills/nuxt-ui/references/layouts/chat.md +140 -77
- package/template/.claude/skills/nuxt-ui/references/layouts/dashboard.md +33 -19
- package/template/.claude/skills/nuxt-ui/references/layouts/docs.md +23 -12
- package/template/.claude/skills/nuxt-ui/references/layouts/editor.md +49 -63
- package/template/.claude/skills/nuxt-ui/references/layouts/{page.md → landing.md} +43 -118
- package/template/.claude/skills/nuxt-ui/references/recipes/auth.md +162 -0
- package/template/.claude/skills/nuxt-ui/references/recipes/data-tables.md +249 -0
- package/template/.claude/skills/nuxt-ui/references/recipes/navigation.md +90 -0
- package/template/.claude/skills/nuxt-ui/references/recipes/overlays.md +177 -0
- package/template/.claude/skills/nuxt-ui-mobile/SKILL.md +38 -10
- package/template/.claude/skills/nuxt-ui-mobile/references/identity.md +127 -0
- package/template/.claude/skills/nuxt-ui-mobile/references/patterns.md +1 -0
- package/template/.claude/skills/nuxt-ui-mobile/references/review-checklist.md +14 -6
- package/template/.claude/skills/nuxt-ui-mobile/references/tokens.md +1 -1
- package/template/.claude/skills/nuxt-ui-mobile/template/app/assets/css/main.css +9 -9
- package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListSection.vue +7 -3
- package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/NavBar.vue +13 -4
- package/template/.claude/skills/nuxt-ui-mobile/template/nuxt.config.ts +2 -1
- package/template/AGENTS.md +175 -9
- package/template/drizzle/20261005212059_sudden_titania/snapshot.json +46 -25
- package/template/golar.config.ts +5 -0
- package/template/nuxt.config.ts +7 -0
- package/template/package.json +9 -6
- package/template/pnpm-workspace.yaml +2 -0
- package/template/server/api/example-secret.get.ts +8 -0
- package/template/.claude/skills/nuxt-ui/references/composables.md +0 -127
- package/template/.claude/skills/nuxt-ui/references/theming.md +0 -427
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Component Selection
|
|
2
|
+
|
|
3
|
+
Decision matrices for choosing the right component. When in doubt, use the MCP `search-components` tool.
|
|
4
|
+
|
|
5
|
+
## Overlays
|
|
6
|
+
|
|
7
|
+
| Need | Component | Why |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Confirmation dialog, focused task, form | `UModal` | Blocks page interaction, centered, draws focus |
|
|
10
|
+
| Detail panel, settings, secondary content | `USlideover` | Slides from edge, doesn't feel as interruptive as modal |
|
|
11
|
+
| Mobile-first bottom sheet | `UDrawer` | Natural mobile pattern, swipe to dismiss |
|
|
12
|
+
| Contextual info attached to a trigger | `UPopover` | No backdrop, positioned relative to trigger |
|
|
13
|
+
| Simple hover hint | `UTooltip` | Non-interactive, hover/focus only |
|
|
14
|
+
|
|
15
|
+
### Rules
|
|
16
|
+
- Use `UModal` for destructive confirmations ("Are you sure you want to delete?")
|
|
17
|
+
- Use `USlideover` for detail views in dashboards (email preview, user profile)
|
|
18
|
+
- Use `UDrawer` for mobile navigation or action sheets
|
|
19
|
+
- Use `UDashboardSidebar` with `mode="drawer"` for a drawer-based mobile menu; `UModal` and `USlideover` don't expose a `mode` prop
|
|
20
|
+
- For programmatic overlays, use `useOverlay()` instead of `v-model:open`
|
|
21
|
+
- Never put interactive content (buttons, links) inside `UTooltip`
|
|
22
|
+
|
|
23
|
+
## Navigation
|
|
24
|
+
|
|
25
|
+
| Need | Component | Why |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| Primary site/app navigation | `UNavigationMenu` | Horizontal (header) or vertical (sidebar) |
|
|
28
|
+
| Switch between views on same page | `UTabs` | Content stays on page, no route change needed |
|
|
29
|
+
| Show current location in hierarchy | `UBreadcrumb` | Nested page structures |
|
|
30
|
+
| Search + keyboard-driven navigation | `UCommandPalette` | Power users, global search |
|
|
31
|
+
| Contextual actions on a trigger element | `UDropdownMenu` | Right-click menus, action buttons |
|
|
32
|
+
| Step-by-step process | `UStepper` | Multi-step forms, wizards |
|
|
33
|
+
|
|
34
|
+
### Rules
|
|
35
|
+
- Use `UNavigationMenu` with `orientation="vertical"` in sidebars, default horizontal in headers
|
|
36
|
+
- Use `UTabs` when switching views that don't need their own URL
|
|
37
|
+
- Use route-based navigation (`to` prop) when views should have shareable URLs
|
|
38
|
+
- `UCommandPalette` is typically opened via `Cmd+K` shortcut — use `defineShortcuts` to wire it up
|
|
39
|
+
|
|
40
|
+
## Inputs
|
|
41
|
+
|
|
42
|
+
| Need | Component | Why |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| Small fixed list (< 10 items) | `USelect` | Native-like, simple, lightweight |
|
|
45
|
+
| Searchable list, multiple selection, groups | `USelectMenu` | Rich dropdown with search, multi-select, grouped items |
|
|
46
|
+
| Autocomplete / combobox (type + select) | `UInputMenu` | User can type freely AND pick from suggestions |
|
|
47
|
+
| Free text entry | `UInput` | Plain text, email, password, search |
|
|
48
|
+
| Multi-line text | `UTextarea` | With `autoresize` and `maxrows` |
|
|
49
|
+
| Numeric value with +/- controls | `UInputNumber` | Min/max/step constraints |
|
|
50
|
+
| Date selection | `UInputDate` | Calendar dropdown, supports ranges |
|
|
51
|
+
| Time selection | `UInputTime` | Hour/minute picker, 12/24 hour |
|
|
52
|
+
| Tags / multi-value free text | `UInputTags` | Chip-style input with max limit |
|
|
53
|
+
| Verification code | `UPinInput` | Fixed-length code entry |
|
|
54
|
+
| Boolean toggle | `USwitch` | On/off, enable/disable |
|
|
55
|
+
| Boolean checkbox | `UCheckbox` | Single option with label |
|
|
56
|
+
| Multiple choices from a list | `UCheckboxGroup` | Multiple selection, vertical or horizontal |
|
|
57
|
+
| Single choice from a list (visible) | `URadioGroup` | All options visible, one selected |
|
|
58
|
+
| Range value | `USlider` | Min/max with visual track |
|
|
59
|
+
| Color value | `UColorPicker` | Hex/RGB/HSL picker |
|
|
60
|
+
| File upload | `UFileUpload` | Button or drop area variants |
|
|
61
|
+
|
|
62
|
+
### Rules
|
|
63
|
+
- Use `UAuthForm` for login/signup pages — handles fields, social providers, validation, and layout out of the box
|
|
64
|
+
- Use `USelect` for short, known lists (country, status, role)
|
|
65
|
+
- Use `USelectMenu` when the list is long or needs search
|
|
66
|
+
- Use `UInputMenu` when the user might want to type a value that's not in the list
|
|
67
|
+
- Wrap all form inputs in `UFormField` for labels, descriptions, hints, and validation errors
|
|
68
|
+
- Group related inline inputs with `UFieldGroup`
|
|
69
|
+
|
|
70
|
+
## Feedback
|
|
71
|
+
|
|
72
|
+
| Need | Component | Why |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| Ephemeral notification after action | `useToast()` | Auto-dismisses, stacks, non-blocking |
|
|
75
|
+
| Inline persistent message | `UAlert` | Stays visible, in-page context |
|
|
76
|
+
| App-wide announcement | `UBanner` | Sticky top bar, dismissible |
|
|
77
|
+
| Loading state | `USkeleton` | Placeholder shimmer while loading |
|
|
78
|
+
| Progress indicator | `UProgress` | Determinate or indeterminate progress |
|
|
79
|
+
| Breakdown of a total | `UProgressGroup` | One bar split into colored segments that add up to `max` |
|
|
80
|
+
|
|
81
|
+
### Rules
|
|
82
|
+
- Use `useToast()` for action feedback: "Item saved", "Email sent", "Error occurred"
|
|
83
|
+
- Use `UAlert` for contextual warnings in forms or sections
|
|
84
|
+
- Use `UBanner` for site-wide messages (maintenance, new feature)
|
|
85
|
+
- Never use a toast for information the user needs to act on — use an alert or modal instead
|
|
86
|
+
|
|
87
|
+
## Markdown
|
|
88
|
+
|
|
89
|
+
When rendering Markdown (for instance with Comark), **prefer Prose components** — they are styled and tuned for Markdown contexts. Generic Nuxt UI components can also be used. `<ComarkRenderer>` (or `<Comark>`) auto-resolves `ProseX` components when `@nuxt/ui` is installed. In Markdown, the `Prose` prefix can be omitted (`::callout`, `::steps`, etc.).
|
|
90
|
+
|
|
91
|
+
| Need | Use | Not |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| Note / warning / tip | `Callout` | `UAlert` |
|
|
94
|
+
| Tabbed content | `Tabs` + `TabsItem` | `UTabs` |
|
|
95
|
+
| Step-by-step list | `Steps` | custom list |
|
|
96
|
+
| Content card grid | `Card` + `CardGroup` | `UCard` |
|
|
97
|
+
| Collapsible section | `Collapsible` / `Accordion` | `UCollapsible` / `UAccordion` |
|
|
98
|
+
| Tabbed code blocks | `CodeGroup` | manual tabs |
|
|
99
|
+
|
|
100
|
+
### Rules
|
|
101
|
+
- Prose components use native Vue slots — Comark maps named `#slot` blocks directly to `<slot name="..." />`
|
|
102
|
+
- Theme via `appConfig.ui.prose.<name>` using the same override pattern as other Nuxt UI components
|
|
103
|
+
- `Callout` colors: `neutral` (default), `primary`, `secondary`, `info`, `success`, `warning`, `error`
|
|
104
|
+
|
|
105
|
+
## Layout containers
|
|
106
|
+
|
|
107
|
+
| Need | Component | Why |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| Grouped content with header/body/footer | `UCard` | Bordered/shadow container with slots |
|
|
110
|
+
| Rich content card with icon, badge, links | `UPageCard` | Extended card for grids — supports icon, badge, highlight, links |
|
|
111
|
+
| Marketing page section | `UPageSection` | Full-width section with headline, title, features |
|
|
112
|
+
| Page hero | `UPageHero` | Title + description + links + optional media |
|
|
113
|
+
| Call to action | `UPageCTA` | Highlighted section with action links |
|
|
114
|
+
| Feature grid | `UPageGrid` + `UPageCard` | Multi-column card grid |
|
|
115
|
+
| Centered content wrapper | `UContainer` | Max-width container |
|
|
116
|
+
| Collapsible section | `UCollapsible` | Animated expand/collapse |
|
|
117
|
+
| Accordion (multiple collapsibles) | `UAccordion` | FAQ, grouped collapsible content |
|
|
118
|
+
| Resizable side-by-side panes | `USplitter` | IDE-style layouts, resizable sidebars |
|
|
119
|
+
|
|
120
|
+
### Rules
|
|
121
|
+
- Don't overuse `UCard` — plain content with spacing is often better than wrapping everything in cards
|
|
122
|
+
- Use `UPageCard` instead of `UCard` when you need icon, badge, highlight, or links — it's designed for feature grids and landing pages
|
|
123
|
+
- Use `UPageSection` for marketing/landing page sections, not for app UI
|
|
124
|
+
- Use `UContainer` inside `UDashboardPanel` body for consistent content width
|
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
# Conventions
|
|
2
|
+
|
|
3
|
+
Coding patterns specific to Nuxt UI.
|
|
4
|
+
|
|
5
|
+
## Auto-registered modules
|
|
6
|
+
|
|
7
|
+
Nuxt 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
|
|
11
|
+
export 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
|
+
|
|
19
|
+
Disable any of them: `ui: { fonts: false }`, `ui: { colorMode: false }`.
|
|
20
|
+
|
|
21
|
+
## Content module integration
|
|
22
|
+
|
|
23
|
+
When 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
|
|
27
|
+
export default defineNuxtConfig({
|
|
28
|
+
modules: ['@nuxt/ui', '@nuxt/content']
|
|
29
|
+
})
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Add `@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
|
+
|
|
42
|
+
Use `mapContentNavigation` to transform content navigation for components like `UBreadcrumb`:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { mapContentNavigation } from '@nuxt/ui/utils/content'
|
|
46
|
+
import { findPageBreadcrumb } from '@nuxt/content/utils'
|
|
47
|
+
|
|
48
|
+
const breadcrumb = computed(() =>
|
|
49
|
+
mapContentNavigation(findPageBreadcrumb(navigation.value, page.value?.path))
|
|
50
|
+
)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## IDE setup
|
|
54
|
+
|
|
55
|
+
Recommended `.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
|
+
|
|
68
|
+
Always 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
|
+
|
|
82
|
+
Nuxt 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
|
+
|
|
90
|
+
Install collections locally for reliable SSR and best performance:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pnpm i @iconify-json/lucide
|
|
94
|
+
pnpm i @iconify-json/simple-icons
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Custom local collections (Nuxt only):
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
// nuxt.config.ts
|
|
101
|
+
export default defineNuxtConfig({
|
|
102
|
+
icon: {
|
|
103
|
+
customCollections: [{
|
|
104
|
+
prefix: 'custom',
|
|
105
|
+
dir: './app/assets/icons'
|
|
106
|
+
}]
|
|
107
|
+
}
|
|
108
|
+
})
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Default icon overrides
|
|
112
|
+
|
|
113
|
+
Components like `Modal`, `Select`, `Accordion`, etc. use default icons from `appConfig.ui.icons`. Override them globally:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
// app.config.ts
|
|
117
|
+
export 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
|
+
|
|
134
|
+
Most 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
|
+
|
|
150
|
+
Many components accept an `items` prop. Two patterns:
|
|
151
|
+
|
|
152
|
+
**Flat array** — plain list:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
const 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
|
|
164
|
+
const 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
|
+
|
|
175
|
+
Components supporting nested arrays: `UDropdownMenu`, `UContextMenu`, `UNavigationMenu`.
|
|
176
|
+
`UCommandPalette` uses a `groups` prop instead, with an `items` array on each group.
|
|
177
|
+
|
|
178
|
+
## Composables
|
|
179
|
+
|
|
180
|
+
### useToast
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
const toast = useToast()
|
|
184
|
+
|
|
185
|
+
toast.add({
|
|
186
|
+
title: 'Success',
|
|
187
|
+
description: 'Item saved',
|
|
188
|
+
color: 'success',
|
|
189
|
+
icon: 'i-lucide-check-circle',
|
|
190
|
+
duration: 5000,
|
|
191
|
+
actions: [{ label: 'Undo', onClick: () => {} }]
|
|
192
|
+
})
|
|
193
|
+
|
|
194
|
+
toast.remove('toast-id')
|
|
195
|
+
toast.clear()
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### useOverlay
|
|
199
|
+
|
|
200
|
+
Programmatic modals, slideovers, drawers — no template `v-model` needed. See [overlays recipe](../recipes/overlays.md) for full patterns.
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
const overlay = useOverlay()
|
|
204
|
+
const modal = overlay.create(MyComponent)
|
|
205
|
+
const instance = modal.open({ title: 'Confirm?' })
|
|
206
|
+
if (await instance.result) { /* confirmed */ }
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### defineShortcuts
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
defineShortcuts({
|
|
213
|
+
meta_k: () => openSearch(),
|
|
214
|
+
escape: () => close(),
|
|
215
|
+
meta_enter: {
|
|
216
|
+
handler: () => submit(),
|
|
217
|
+
whenever: [isFormValid]
|
|
218
|
+
}
|
|
219
|
+
})
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Keys: `meta` (Cmd/Ctrl), `ctrl`, `alt`, `shift`. Separator: `_`.
|
|
223
|
+
|
|
224
|
+
### extractShortcuts
|
|
225
|
+
|
|
226
|
+
Wire up keyboard shortcuts from menu items:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
const items = [
|
|
230
|
+
{ label: 'New file', kbds: ['meta', 'n'], onSelect: () => newFile() },
|
|
231
|
+
{ label: 'Save', kbds: ['meta', 's'], onSelect: () => save() }
|
|
232
|
+
]
|
|
233
|
+
|
|
234
|
+
defineShortcuts(extractShortcuts(items))
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### Internationalization (i18n)
|
|
238
|
+
|
|
239
|
+
Nuxt UI supports 50+ locales. Set the locale on `UApp` — all components inherit it.
|
|
240
|
+
|
|
241
|
+
#### Static locale
|
|
242
|
+
|
|
243
|
+
```vue
|
|
244
|
+
<script setup lang="ts">
|
|
245
|
+
import { fr } from '@nuxt/ui/locale'
|
|
246
|
+
</script>
|
|
247
|
+
|
|
248
|
+
<template>
|
|
249
|
+
<UApp :locale="fr">
|
|
250
|
+
<NuxtPage />
|
|
251
|
+
</UApp>
|
|
252
|
+
</template>
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
#### Extend a built-in locale
|
|
256
|
+
|
|
257
|
+
`extendLocale` is auto-imported. Override specific messages or the `code` (affects date/time formatting in Calendar, InputDate, InputTime):
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
import { en } from '@nuxt/ui/locale'
|
|
261
|
+
|
|
262
|
+
const locale = extendLocale(en, {
|
|
263
|
+
code: 'en-AU',
|
|
264
|
+
messages: {
|
|
265
|
+
commandPalette: { placeholder: 'Search a component...' }
|
|
266
|
+
}
|
|
267
|
+
})
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
#### Custom locale from scratch
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
import type { Messages } from '@nuxt/ui'
|
|
274
|
+
|
|
275
|
+
const locale = defineLocale<Messages>({
|
|
276
|
+
name: 'My locale',
|
|
277
|
+
code: 'en',
|
|
278
|
+
dir: 'ltr',
|
|
279
|
+
messages: {
|
|
280
|
+
// all component message keys
|
|
281
|
+
}
|
|
282
|
+
})
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
#### Dynamic locale with @nuxtjs/i18n
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
// nuxt.config.ts
|
|
289
|
+
export default defineNuxtConfig({
|
|
290
|
+
modules: ['@nuxt/ui', '@nuxtjs/i18n'],
|
|
291
|
+
i18n: {
|
|
292
|
+
locales: [
|
|
293
|
+
{ code: 'en', language: 'en', name: 'English' },
|
|
294
|
+
{ code: 'fr', language: 'fr', name: 'Français' },
|
|
295
|
+
{ code: 'ar', language: 'ar', dir: 'rtl', name: 'العربية' }
|
|
296
|
+
]
|
|
297
|
+
}
|
|
298
|
+
})
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
```vue
|
|
302
|
+
<script setup lang="ts">
|
|
303
|
+
const head = useLocaleHead()
|
|
304
|
+
|
|
305
|
+
useHead(() => ({
|
|
306
|
+
htmlAttrs: head.value.htmlAttrs
|
|
307
|
+
}))
|
|
308
|
+
</script>
|
|
309
|
+
|
|
310
|
+
<template>
|
|
311
|
+
<UApp>
|
|
312
|
+
<NuxtPage />
|
|
313
|
+
</UApp>
|
|
314
|
+
</template>
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
With `@nuxtjs/i18n` installed, `UApp` follows the current i18n locale and only bundles the Nuxt UI locales matching `i18n.locales`. Don't use `import * as locales from '@nuxt/ui/locale'`: it bundles every locale. Use `useLocaleHead` to propagate `lang` and `dir` to the `<html>` element.
|
|
318
|
+
|
|
319
|
+
## Color mode
|
|
320
|
+
|
|
321
|
+
Nuxt UI registers `@nuxtjs/color-mode` automatically. Built-in components for switching:
|
|
322
|
+
- `UColorModeButton` — single button toggle (light/dark)
|
|
323
|
+
- `UColorModeSwitch` — toggle switch
|
|
324
|
+
- `UColorModeSelect` — dropdown with system/light/dark options
|
|
325
|
+
- `UColorModeAvatar` — displays different avatar per mode
|
|
326
|
+
- `UColorModeImage` — displays different image per mode
|
|
327
|
+
|
|
328
|
+
For custom color mode UI, use `useColorMode` with `ClientOnly` to avoid hydration mismatch:
|
|
329
|
+
|
|
330
|
+
```vue
|
|
331
|
+
<script setup lang="ts">
|
|
332
|
+
const colorMode = useColorMode()
|
|
333
|
+
|
|
334
|
+
const isDark = computed({
|
|
335
|
+
get: () => colorMode.value === 'dark',
|
|
336
|
+
set: (v) => { colorMode.preference = v ? 'dark' : 'light' }
|
|
337
|
+
})
|
|
338
|
+
</script>
|
|
339
|
+
|
|
340
|
+
<template>
|
|
341
|
+
<ClientOnly>
|
|
342
|
+
<USwitch v-model="isDark" />
|
|
343
|
+
<template #fallback>
|
|
344
|
+
<div class="size-8" />
|
|
345
|
+
</template>
|
|
346
|
+
</ClientOnly>
|
|
347
|
+
</template>
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Official templates
|
|
351
|
+
|
|
352
|
+
Bootstrap a project from a template instead of starting from scratch:
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
npm create nuxt@latest -- -t ui # Starter
|
|
356
|
+
npm create nuxt@latest -- -t ui/dashboard # Dashboard
|
|
357
|
+
npm create nuxt@latest -- -t ui/docs # Docs (Nuxt Content)
|
|
358
|
+
npm create nuxt@latest -- -t ui/landing # Landing page
|
|
359
|
+
npm create nuxt@latest -- -t ui/saas # SaaS (landing + pricing + docs + blog)
|
|
360
|
+
npm create nuxt@latest -- -t ui/chat # AI chat (Vercel AI SDK)
|
|
361
|
+
npm create nuxt@latest -- -t ui/editor # Rich text editor
|
|
362
|
+
npm create nuxt@latest -- -t ui/portfolio # Portfolio
|
|
363
|
+
npm create nuxt@latest -- -t ui/changelog # Changelog
|
|
364
|
+
npm create nuxt@latest -- -t ui/calendar # Calendar
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
## Responsive patterns
|
|
368
|
+
|
|
369
|
+
- Dashboard sidebar hides on mobile, shows a slideover/drawer via `UDashboardSidebar` `mode` prop
|
|
370
|
+
- `UHeader` body slot is the mobile menu content (shown when hamburger is tapped)
|
|
371
|
+
- Most components handle responsiveness automatically — avoid manual breakpoint classes unless needed
|
|
372
|
+
- Use `UPageAside` for sidebars that should hide below `lg` breakpoint
|