1# Forms
2 
3## Basic pattern
4 
5Nuxt UI forms use `UForm` + `UFormField` + Standard Schema validation (Zod, Valibot, Yup, or Joi).
6 
7```vue
8<script setup lang="ts">
9import * as z from 'zod'
10import type { FormSubmitEvent } from '@nuxt/ui'
11 
12const schema = z.object({
13  email: z.email('Invalid email'),
14  password: z.string().min(8, 'Min 8 characters')
15})
16 
17type Schema = z.output<typeof schema>
18const state = reactive<Partial<Schema>>({ email: '', password: '' })
19 
20function 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="[email protected]" />
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">
181const form = useTemplateRef('form')
182 
183async function validateAndSubmit() {
184  const result = await form.value?.validate()
185  if (result) {
186    // valid — submit
187  }
188}
189 
190async function validateEmail() {
191  await form.value?.validate({ name: 'email' })
192}
193 
194function setServerError() {
195  form.value?.setErrors([
196    { name: 'email', message: 'Email already taken' }
197  ])
198}
199 
200function resetErrors() {
201  form.value?.clearErrors()
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## Form in a modal
213 
214Use `#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.
215 
216```vue
217<UModal v-model:open="isOpen" title="Edit profile" description="Update your information." :ui="{ footer: 'justify-end' }">
218  <template #body>
219    <UForm id="profile-form" :schema="schema" :state="state" class="space-y-4" @submit="onSave">
220      <UFormField name="name" label="Name">
221        <UInput v-model="state.name" />
222      </UFormField>
223      <UFormField name="email" label="Email">
224        <UInput v-model="state.email" type="email" />
225      </UFormField>
226    </UForm>
227  </template>
228  <template #footer="{ close }">
229    <UButton label="Cancel" color="neutral" variant="outline" @click="close" />
230    <UButton type="submit" form="profile-form" label="Save" />
231  </template>
232</UModal>
233```
234