create-wervt 0.2.15 → 0.2.17
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/.claude/skills/wervt-logs/SKILL.md +16 -13
- package/template/AGENTS.md +120 -8
- package/template/golar.config.ts +5 -0
- package/template/package.json +7 -4
- package/template/pnpm-workspace.yaml +2 -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,378 @@
|
|
|
1
|
+
# Design System
|
|
2
|
+
|
|
3
|
+
## Semantic colors
|
|
4
|
+
|
|
5
|
+
Nuxt UI uses 7 semantic colors. Never use raw Tailwind palette colors in components — always use these semantic names.
|
|
6
|
+
|
|
7
|
+
| Color | Default | When to use |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `primary` | green | CTAs, active states, brand accent, links |
|
|
10
|
+
| `secondary` | blue | Secondary actions, complementary highlights |
|
|
11
|
+
| `success` | green | Success messages, confirmations, positive states |
|
|
12
|
+
| `info` | blue | Informational alerts, tips, neutral highlights |
|
|
13
|
+
| `warning` | yellow | Warnings, caution states, pending actions |
|
|
14
|
+
| `error` | red | Errors, destructive actions, validation failures |
|
|
15
|
+
| `neutral` | slate | Text, borders, backgrounds, disabled states, chrome |
|
|
16
|
+
|
|
17
|
+
### Choosing colors for components
|
|
18
|
+
|
|
19
|
+
- **Primary action** on a page (submit, save, confirm) → `color="primary"`
|
|
20
|
+
- **Secondary actions** (cancel, back, alternative) → `color="neutral"` with `variant="outline"` or `"ghost"`
|
|
21
|
+
- **Destructive actions** (delete, remove) → `color="error"`
|
|
22
|
+
- **Status indicators** → match the semantic meaning: `success`, `warning`, `error`, `info`
|
|
23
|
+
- **Navigation and chrome** → `color="neutral"`
|
|
24
|
+
|
|
25
|
+
### Configuring colors
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
// Nuxt — app.config.ts
|
|
29
|
+
export default defineAppConfig({
|
|
30
|
+
ui: {
|
|
31
|
+
colors: {
|
|
32
|
+
primary: 'indigo',
|
|
33
|
+
secondary: 'violet',
|
|
34
|
+
success: 'emerald',
|
|
35
|
+
error: 'rose',
|
|
36
|
+
neutral: 'zinc'
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
})
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
// Vue — vite.config.ts
|
|
44
|
+
ui({
|
|
45
|
+
ui: {
|
|
46
|
+
colors: { primary: 'indigo', secondary: 'violet', neutral: 'zinc' }
|
|
47
|
+
}
|
|
48
|
+
})
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Only colors that exist in your theme work — either Tailwind's defaults or custom colors defined with `@theme`.
|
|
52
|
+
|
|
53
|
+
Available color palettes:
|
|
54
|
+
- **Standard Tailwind**: red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose
|
|
55
|
+
- **Neutral palettes** (for `neutral` key — pick one that matches the aesthetic):
|
|
56
|
+
- `slate` — cool blue-gray, professional (default)
|
|
57
|
+
- `gray` — true neutral, clean
|
|
58
|
+
- `zinc` — slightly cool, modern, techy
|
|
59
|
+
- `neutral` — perfectly balanced
|
|
60
|
+
- `stone` — warm gray, earthy
|
|
61
|
+
- `taupe` — warm brown-gray, sophisticated
|
|
62
|
+
- `mauve` — purple-tinted gray, elegant
|
|
63
|
+
- `mist` — soft blue-gray, airy
|
|
64
|
+
- `olive` — green-tinted gray, natural
|
|
65
|
+
|
|
66
|
+
### Adding custom brand colors
|
|
67
|
+
|
|
68
|
+
1. Define all 11 shades in CSS:
|
|
69
|
+
|
|
70
|
+
```css
|
|
71
|
+
/* app/assets/css/main.css */
|
|
72
|
+
@theme static {
|
|
73
|
+
--color-brand-50: #fef2f2;
|
|
74
|
+
--color-brand-100: #fee2e2;
|
|
75
|
+
--color-brand-200: #fecaca;
|
|
76
|
+
--color-brand-300: #fca5a5;
|
|
77
|
+
--color-brand-400: #f87171;
|
|
78
|
+
--color-brand-500: #ef4444;
|
|
79
|
+
--color-brand-600: #dc2626;
|
|
80
|
+
--color-brand-700: #b91c1c;
|
|
81
|
+
--color-brand-800: #991b1b;
|
|
82
|
+
--color-brand-900: #7f1d1d;
|
|
83
|
+
--color-brand-950: #450a0a;
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
2. Assign it: `ui: { colors: { primary: 'brand' } }`
|
|
88
|
+
|
|
89
|
+
### Extending with new semantic color names
|
|
90
|
+
|
|
91
|
+
To add a color beyond the 7 defaults (e.g., `tertiary`), register it in `theme.colors`:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
// nuxt.config.ts
|
|
95
|
+
export default defineNuxtConfig({
|
|
96
|
+
ui: {
|
|
97
|
+
theme: {
|
|
98
|
+
colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error']
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Semantic utility classes
|
|
105
|
+
|
|
106
|
+
Use these everywhere instead of raw palette colors:
|
|
107
|
+
|
|
108
|
+
### Text
|
|
109
|
+
- `text-default` — primary body text
|
|
110
|
+
- `text-muted` — secondary text (descriptions, hints)
|
|
111
|
+
- `text-toned` — medium-emphasis text (between muted and default)
|
|
112
|
+
- `text-dimmed` — tertiary text (placeholders, disabled)
|
|
113
|
+
- `text-highlighted` — emphasized text (headings, important labels)
|
|
114
|
+
- `text-inverted` — text on inverted backgrounds (pair with `bg-inverted`)
|
|
115
|
+
|
|
116
|
+
### Backgrounds
|
|
117
|
+
- `bg-default` — page background
|
|
118
|
+
- `bg-muted` — subtle backgrounds (hover states, alternating rows)
|
|
119
|
+
- `bg-elevated` — raised surfaces (cards, dropdowns)
|
|
120
|
+
- `bg-accented` — accent backgrounds (active states, selected items)
|
|
121
|
+
- `bg-inverted` — inverse background (dark on light, light on dark)
|
|
122
|
+
|
|
123
|
+
### Borders
|
|
124
|
+
- `border-default` — standard borders
|
|
125
|
+
- `border-muted` — subtle borders (dividers, separators)
|
|
126
|
+
- `border-accented` — accent borders (active states)
|
|
127
|
+
- `border-inverted` — inverse borders
|
|
128
|
+
|
|
129
|
+
## Variants
|
|
130
|
+
|
|
131
|
+
Most components accept a `variant` prop. Choose based on visual weight:
|
|
132
|
+
|
|
133
|
+
| Variant | Weight | When to use |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| `solid` | Highest | Primary actions, main CTAs |
|
|
136
|
+
| `outline` | Medium | Secondary actions, form fields |
|
|
137
|
+
| `soft` | Medium-low | Tags, badges, subtle buttons |
|
|
138
|
+
| `subtle` | Low | Background highlights, less prominent actions |
|
|
139
|
+
| `ghost` | Lowest | Inline actions, icon buttons, navigation items |
|
|
140
|
+
| `link` | Lowest | Text-only links inside content |
|
|
141
|
+
|
|
142
|
+
### Rules
|
|
143
|
+
|
|
144
|
+
- **One solid primary button per view** — everything else should be lower weight
|
|
145
|
+
- **Destructive buttons** use `color="error"` but not necessarily `variant="solid"` — use `variant="soft"` or `"outline"` unless it's the primary action on a confirmation dialog
|
|
146
|
+
- **Button groups** should use consistent variants — don't mix `solid` and `outline` siblings
|
|
147
|
+
|
|
148
|
+
## Customizing components
|
|
149
|
+
|
|
150
|
+
### `ui` prop
|
|
151
|
+
|
|
152
|
+
Override theme **slots** on a single instance — wins over global config and variants.
|
|
153
|
+
|
|
154
|
+
```vue
|
|
155
|
+
<UButton :ui="{ base: 'font-bold', trailingIcon: 'size-3 rotate-90' }" />
|
|
156
|
+
<UCard :ui="{ header: 'bg-muted', body: 'p-8' }" />
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Rules for `ui` overrides:
|
|
160
|
+
- **Prefer `defaultVariants`** over slot class overrides when possible (e.g., changing default button variant/size).
|
|
161
|
+
- **Don't duplicate default classes** — check the generated theme file first to see what's already there.
|
|
162
|
+
- Border radius defaults come from `--ui-radius`, but you can override with `rounded-*` classes in `ui` or `class` when you need a specific radius on a component.
|
|
163
|
+
|
|
164
|
+
### `class` prop
|
|
165
|
+
|
|
166
|
+
Override the **root** (or `base`) slot only — simpler than `ui` for single-slot changes.
|
|
167
|
+
|
|
168
|
+
```vue
|
|
169
|
+
<UButton class="font-bold" />
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Finding slot names
|
|
173
|
+
|
|
174
|
+
Read the generated theme file for any component:
|
|
175
|
+
- **Nuxt**: `.nuxt/ui/<component>.ts`
|
|
176
|
+
- **Vue**: `node_modules/.nuxt-ui/ui/<component>.ts`
|
|
177
|
+
|
|
178
|
+
These files show every available slot name, variant combination, and default class.
|
|
179
|
+
|
|
180
|
+
### Global config
|
|
181
|
+
|
|
182
|
+
Override `slots`, `variants`, `compoundVariants`, and `defaultVariants` globally in `app.config.ts` (Nuxt) or `vite.config.ts` (Vue):
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
// Nuxt — app.config.ts
|
|
186
|
+
export default defineAppConfig({
|
|
187
|
+
ui: {
|
|
188
|
+
button: {
|
|
189
|
+
slots: {
|
|
190
|
+
base: 'font-bold'
|
|
191
|
+
},
|
|
192
|
+
compoundVariants: [{
|
|
193
|
+
color: 'neutral',
|
|
194
|
+
variant: 'outline',
|
|
195
|
+
class: 'ring-default hover:bg-accented'
|
|
196
|
+
}],
|
|
197
|
+
defaultVariants: {
|
|
198
|
+
color: 'neutral',
|
|
199
|
+
variant: 'outline'
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
})
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Tailwind Variants uses `tailwind-merge` under the hood — conflicting classes are resolved automatically.
|
|
207
|
+
|
|
208
|
+
### Replace instead of merge
|
|
209
|
+
|
|
210
|
+
Classes from the `ui` prop, the `class` prop, and global config are merged onto the component defaults. To replace them instead, set the slot to a function, which receives the default classes as its argument so you can reuse part of them.
|
|
211
|
+
|
|
212
|
+
In global config it replaces the slot's own classes, so `variants` and `compoundVariants` still apply on top. In the `ui` and `class` props it runs after the variants, so it replaces the resolved classes, variants included.
|
|
213
|
+
|
|
214
|
+
```vue
|
|
215
|
+
<UButton :ui="{ label: () => 'text-base font-bold' }" />
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
// app.config.ts, applies to every instance
|
|
220
|
+
export default defineAppConfig({
|
|
221
|
+
ui: {
|
|
222
|
+
button: {
|
|
223
|
+
slots: {
|
|
224
|
+
label: () => 'text-base font-bold'
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
})
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Theme component
|
|
232
|
+
|
|
233
|
+
Override theme for a section of the component tree without affecting the rest of the app. Renders no DOM element — uses `provide`/`inject`:
|
|
234
|
+
|
|
235
|
+
```vue
|
|
236
|
+
<UTheme :ui="{ button: { base: 'rounded-full' } }">
|
|
237
|
+
<UButton label="Rounded" />
|
|
238
|
+
<UButton label="Also rounded" />
|
|
239
|
+
</UTheme>
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### Global `defaultVariants`
|
|
243
|
+
|
|
244
|
+
Override default `size` and `color` for **all** components at once:
|
|
245
|
+
|
|
246
|
+
```ts
|
|
247
|
+
// nuxt.config.ts
|
|
248
|
+
export default defineNuxtConfig({
|
|
249
|
+
ui: {
|
|
250
|
+
theme: {
|
|
251
|
+
defaultVariants: {
|
|
252
|
+
size: 'lg',
|
|
253
|
+
color: 'neutral'
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
})
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### `theme.transitions`
|
|
261
|
+
|
|
262
|
+
Controls whether interactive components get `transition-colors`. Enabled by default.
|
|
263
|
+
|
|
264
|
+
```ts
|
|
265
|
+
// nuxt.config.ts — disable transitions
|
|
266
|
+
export default defineNuxtConfig({
|
|
267
|
+
ui: {
|
|
268
|
+
theme: {
|
|
269
|
+
transitions: false
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
})
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### `theme.prefix`
|
|
276
|
+
|
|
277
|
+
When using Tailwind CSS with a prefix, configure the same prefix in Nuxt UI so component classes match:
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
// nuxt.config.ts
|
|
281
|
+
export default defineNuxtConfig({
|
|
282
|
+
ui: {
|
|
283
|
+
theme: {
|
|
284
|
+
prefix: 'tw'
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
})
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
```css
|
|
291
|
+
/* app/assets/css/main.css */
|
|
292
|
+
@import "tailwindcss" prefix(tw);
|
|
293
|
+
@import "@nuxt/ui";
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Tree-shaking with `experimental.componentDetection`
|
|
297
|
+
|
|
298
|
+
Enable automatic component detection to only generate CSS for components you actually use:
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
// nuxt.config.ts
|
|
302
|
+
export default defineNuxtConfig({
|
|
303
|
+
ui: {
|
|
304
|
+
experimental: {
|
|
305
|
+
componentDetection: true
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
})
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
For dynamic components (e.g., `<component :is="...">`), pass an array of component names to guarantee they're included:
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
componentDetection: ['Modal', 'DropdownMenu', 'Popover']
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
## CSS `@theme` customization
|
|
318
|
+
|
|
319
|
+
Customize Tailwind design tokens in `main.css`:
|
|
320
|
+
|
|
321
|
+
### Fonts
|
|
322
|
+
|
|
323
|
+
```css
|
|
324
|
+
@theme {
|
|
325
|
+
--font-sans: 'Public Sans', system-ui, sans-serif;
|
|
326
|
+
--font-mono: 'JetBrains Mono', monospace;
|
|
327
|
+
}
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
In Nuxt, fonts defined here are automatically loaded by `@nuxt/fonts`.
|
|
331
|
+
|
|
332
|
+
### Breakpoints
|
|
333
|
+
|
|
334
|
+
```css
|
|
335
|
+
@theme {
|
|
336
|
+
--breakpoint-3xl: 1920px;
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
## CSS variables
|
|
341
|
+
|
|
342
|
+
Nuxt UI exposes CSS variables you can override in `main.css`:
|
|
343
|
+
|
|
344
|
+
```css
|
|
345
|
+
:root {
|
|
346
|
+
--ui-radius: 0.25rem;
|
|
347
|
+
--ui-container: 80rem;
|
|
348
|
+
--ui-header-height: 4rem;
|
|
349
|
+
}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
### Color shade overrides
|
|
353
|
+
|
|
354
|
+
Each semantic color defaults to shade 500 in light mode, 400 in dark mode. Override per-mode:
|
|
355
|
+
|
|
356
|
+
```css
|
|
357
|
+
:root {
|
|
358
|
+
--ui-primary: var(--ui-color-primary-700);
|
|
359
|
+
}
|
|
360
|
+
.dark {
|
|
361
|
+
--ui-primary: var(--ui-color-primary-200);
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
You can use `var(--ui-color-<name>-<shade>)` to reference shades from the active palette (e.g., `var(--ui-color-neutral-800)` maps to whichever neutral palette is configured).
|
|
366
|
+
|
|
367
|
+
### Black/white as primary
|
|
368
|
+
|
|
369
|
+
`black` and `white` have no shades, so they can't be used in config. Set them directly:
|
|
370
|
+
|
|
371
|
+
```css
|
|
372
|
+
:root {
|
|
373
|
+
--ui-primary: black;
|
|
374
|
+
}
|
|
375
|
+
.dark {
|
|
376
|
+
--ui-primary: white;
|
|
377
|
+
}
|
|
378
|
+
```
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# Forms
|
|
2
|
+
|
|
3
|
+
## Basic pattern
|
|
4
|
+
|
|
5
|
+
Nuxt UI forms use `UForm` + `UFormField` + Standard Schema validation (Zod, Valibot, Yup, or Joi).
|
|
6
|
+
|
|
7
|
+
```vue
|
|
8
|
+
<script setup lang="ts">
|
|
9
|
+
import * as z from 'zod'
|
|
10
|
+
import type { FormSubmitEvent } from '@nuxt/ui'
|
|
11
|
+
|
|
12
|
+
const schema = z.object({
|
|
13
|
+
email: z.email('Invalid email'),
|
|
14
|
+
password: z.string().min(8, 'Min 8 characters')
|
|
15
|
+
})
|
|
16
|
+
|
|
17
|
+
type Schema = z.output<typeof schema>
|
|
18
|
+
const state = reactive<Partial<Schema>>({ email: '', password: '' })
|
|
19
|
+
|
|
20
|
+
function onSubmit(event: FormSubmitEvent<Schema>) {
|
|
21
|
+
// UForm validates before emitting @submit — access validated data via event.data
|
|
22
|
+
}
|
|
23
|
+
</script>
|
|
24
|
+
|
|
25
|
+
<template>
|
|
26
|
+
<UForm :schema="schema" :state="state" class="space-y-4" @submit="onSubmit">
|
|
27
|
+
<UFormField name="email" label="Email" required>
|
|
28
|
+
<UInput v-model="state.email" type="email" placeholder="you@example.com" />
|
|
29
|
+
</UFormField>
|
|
30
|
+
|
|
31
|
+
<UFormField name="password" label="Password" required>
|
|
32
|
+
<UInput v-model="state.password" type="password" placeholder="Min 8 characters" />
|
|
33
|
+
</UFormField>
|
|
34
|
+
|
|
35
|
+
<UButton type="submit" label="Sign in" />
|
|
36
|
+
</UForm>
|
|
37
|
+
</template>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Key rules
|
|
41
|
+
|
|
42
|
+
- Always use `UFormField` around inputs — it connects validation errors via the `name` prop
|
|
43
|
+
- The `name` prop on `UFormField` must match the schema field name exactly
|
|
44
|
+
- Use `reactive<Partial<Schema>>({})` for state — `Partial` allows empty initial values
|
|
45
|
+
- `@submit` only fires when validation passes
|
|
46
|
+
- For nested objects, use dot notation: `name="address.city"`
|
|
47
|
+
|
|
48
|
+
## UFormField props
|
|
49
|
+
|
|
50
|
+
| Prop | Purpose |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `name` | Links to schema field for validation errors |
|
|
53
|
+
| `label` | Visible label text |
|
|
54
|
+
| `description` | Help text below the input |
|
|
55
|
+
| `hint` | Right-aligned hint text (e.g., "Optional") |
|
|
56
|
+
| `required` | Shows required indicator |
|
|
57
|
+
| `size` | Inherits to child input |
|
|
58
|
+
|
|
59
|
+
## Field layout patterns
|
|
60
|
+
|
|
61
|
+
### Vertical stack (default)
|
|
62
|
+
|
|
63
|
+
```vue
|
|
64
|
+
<UForm :schema="schema" :state="state" class="space-y-4">
|
|
65
|
+
<UFormField name="name" label="Name">
|
|
66
|
+
<UInput v-model="state.name" />
|
|
67
|
+
</UFormField>
|
|
68
|
+
<UFormField name="email" label="Email">
|
|
69
|
+
<UInput v-model="state.email" />
|
|
70
|
+
</UFormField>
|
|
71
|
+
</UForm>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Inline fields with UFieldGroup
|
|
75
|
+
|
|
76
|
+
```vue
|
|
77
|
+
<UFieldGroup>
|
|
78
|
+
<UFormField name="firstName" label="First name">
|
|
79
|
+
<UInput v-model="state.firstName" />
|
|
80
|
+
</UFormField>
|
|
81
|
+
<UFormField name="lastName" label="Last name">
|
|
82
|
+
<UInput v-model="state.lastName" />
|
|
83
|
+
</UFormField>
|
|
84
|
+
</UFieldGroup>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Grid layout
|
|
88
|
+
|
|
89
|
+
```vue
|
|
90
|
+
<UForm :schema="schema" :state="state" class="grid grid-cols-2 gap-4">
|
|
91
|
+
<UFormField name="firstName" label="First name">
|
|
92
|
+
<UInput v-model="state.firstName" />
|
|
93
|
+
</UFormField>
|
|
94
|
+
<UFormField name="lastName" label="Last name">
|
|
95
|
+
<UInput v-model="state.lastName" />
|
|
96
|
+
</UFormField>
|
|
97
|
+
<UFormField name="email" label="Email" class="col-span-2">
|
|
98
|
+
<UInput v-model="state.email" type="email" />
|
|
99
|
+
</UFormField>
|
|
100
|
+
</UForm>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Common field patterns
|
|
104
|
+
|
|
105
|
+
### Select
|
|
106
|
+
|
|
107
|
+
```vue
|
|
108
|
+
<UFormField name="role" label="Role">
|
|
109
|
+
<USelect v-model="state.role" :items="['Admin', 'Editor', 'Viewer']" placeholder="Choose role" />
|
|
110
|
+
</UFormField>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Checkbox
|
|
114
|
+
|
|
115
|
+
```vue
|
|
116
|
+
<UFormField name="terms">
|
|
117
|
+
<UCheckbox v-model="state.terms" label="I agree to the terms and conditions" />
|
|
118
|
+
</UFormField>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Radio group
|
|
122
|
+
|
|
123
|
+
```vue
|
|
124
|
+
<UFormField name="plan" label="Plan">
|
|
125
|
+
<URadioGroup
|
|
126
|
+
v-model="state.plan"
|
|
127
|
+
:items="[
|
|
128
|
+
{ label: 'Free', value: 'free', description: 'For personal projects' },
|
|
129
|
+
{ label: 'Pro', value: 'pro', description: 'For teams' }
|
|
130
|
+
]"
|
|
131
|
+
/>
|
|
132
|
+
</UFormField>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Switch
|
|
136
|
+
|
|
137
|
+
```vue
|
|
138
|
+
<UFormField name="notifications" label="Email notifications">
|
|
139
|
+
<USwitch v-model="state.notifications" />
|
|
140
|
+
</UFormField>
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Textarea
|
|
144
|
+
|
|
145
|
+
```vue
|
|
146
|
+
<UFormField name="bio" label="Bio" description="Brief description for your profile.">
|
|
147
|
+
<UTextarea v-model="state.bio" :rows="3" autoresize :maxrows="6" />
|
|
148
|
+
</UFormField>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### File upload
|
|
152
|
+
|
|
153
|
+
```vue
|
|
154
|
+
<UFormField name="avatar" label="Avatar">
|
|
155
|
+
<UFileUpload v-model="state.avatar" accept="image/*" />
|
|
156
|
+
</UFormField>
|
|
157
|
+
|
|
158
|
+
<!-- Or as a drop area -->
|
|
159
|
+
<UFormField name="documents" label="Documents">
|
|
160
|
+
<UFileUpload v-model="state.documents" multiple variant="area" />
|
|
161
|
+
</UFormField>
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Date
|
|
165
|
+
|
|
166
|
+
```vue
|
|
167
|
+
<UFormField name="date" label="Date">
|
|
168
|
+
<UInputDate v-model="state.date" />
|
|
169
|
+
</UFormField>
|
|
170
|
+
|
|
171
|
+
<!-- Date range -->
|
|
172
|
+
<UFormField name="dateRange" label="Date range">
|
|
173
|
+
<UInputDate v-model="state.dateRange" range />
|
|
174
|
+
</UFormField>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Programmatic validation
|
|
178
|
+
|
|
179
|
+
```vue
|
|
180
|
+
<script setup lang="ts">
|
|
181
|
+
const form = useTemplateRef('form')
|
|
182
|
+
|
|
183
|
+
async function validateAndSubmit() {
|
|
184
|
+
const result = await form.value?.validate({ silent: true })
|
|
185
|
+
if (result) {
|
|
186
|
+
// valid — submit
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
async function validateEmail() {
|
|
191
|
+
await form.value?.validate({ name: 'email', silent: true })
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
function setServerError() {
|
|
195
|
+
form.value?.setErrors([
|
|
196
|
+
{ name: 'email', message: 'Email already taken' }
|
|
197
|
+
])
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
function resetErrors() {
|
|
201
|
+
form.value?.clear()
|
|
202
|
+
}
|
|
203
|
+
</script>
|
|
204
|
+
|
|
205
|
+
<template>
|
|
206
|
+
<UForm ref="form" :schema="schema" :state="state" @submit="onSubmit">
|
|
207
|
+
<!-- fields -->
|
|
208
|
+
</UForm>
|
|
209
|
+
</template>
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
By default, `validate()` throws a `FormValidationException` when validation fails. Pass `{ silent: true }` when you want it to return `false` instead. Use `clear()` to remove validation errors.
|
|
213
|
+
|
|
214
|
+
## Form in a modal
|
|
215
|
+
|
|
216
|
+
Use `#footer="{ close }"` scoped slot for cancel/submit actions. Wrap the modal body in `UForm` with a `type="submit"` button in the footer so validation runs on submit.
|
|
217
|
+
|
|
218
|
+
```vue
|
|
219
|
+
<UModal v-model:open="isOpen" title="Edit profile" description="Update your information." :ui="{ footer: 'justify-end' }">
|
|
220
|
+
<template #body>
|
|
221
|
+
<UForm id="profile-form" :schema="schema" :state="state" class="space-y-4" @submit="onSave">
|
|
222
|
+
<UFormField name="name" label="Name">
|
|
223
|
+
<UInput v-model="state.name" />
|
|
224
|
+
</UFormField>
|
|
225
|
+
<UFormField name="email" label="Email">
|
|
226
|
+
<UInput v-model="state.email" type="email" />
|
|
227
|
+
</UFormField>
|
|
228
|
+
</UForm>
|
|
229
|
+
</template>
|
|
230
|
+
<template #footer="{ close }">
|
|
231
|
+
<UButton label="Cancel" color="neutral" variant="outline" @click="close" />
|
|
232
|
+
<UButton type="submit" form="profile-form" label="Save" />
|
|
233
|
+
</template>
|
|
234
|
+
</UModal>
|
|
235
|
+
```
|