1# Forms
2 
3## Form Components
4 
5| Component        | Purpose             | Key Props                                     | Version |
6| ---------------- | ------------------- | --------------------------------------------- | ------- |
7| `UInput`         | Text input          | `type`, `placeholder`, `icon`, `loading`      |         |
8| `UTextarea`      | Multi-line text     | `rows`, `autoresize`, `maxrows`               |         |
9| `USelect`        | Native select       | `options`, `placeholder`                      |         |
10| `USelectMenu`    | Custom select       | `options`, `searchable`, `multiple`           |         |
11| `UInputMenu`     | Autocomplete        | `options`, `searchable`                       |         |
12| `UCheckbox`      | Single checkbox     | `label`, `description`                        |         |
13| `UCheckboxGroup` | Multiple checkboxes | `items`, `orientation`                        |         |
14| `URadioGroup`    | Radio options       | `items`, `orientation`                        |         |
15| `USwitch`        | Toggle switch       | `label`, `description`, `on-icon`, `off-icon` |         |
16| `USlider`        | Range slider        | `min`, `max`, `step`                          |         |
17| `UPinInput`      | Code/OTP input      | `length`, `type`, `mask`                      |         |
18| `UInputNumber`   | Number input        | `min`, `max`, `step`, `format-options`        |         |
19| `UInputDate`     | Date picker         | `mode`, `range`, `locale`                     | v4.2+   |
20| `UInputTime`     | Time picker         | `hour-cycle`, `minute-step`                   | v4.2+   |
21| `UInputTags`     | Tag input           | `max`, `placeholder`                          |         |
22| `UColorPicker`   | Color selection     | `format`, `swatches`                          |         |
23| `UFileUpload`    | File upload         | `accept`, `multiple`, `max-files`             |         |
24 
25## Basic Input Examples
26 
27```vue
28<script setup>
29const email = ref('')
30const bio = ref('')
31const country = ref('')
32</script>
33 
34<template>
35  <!-- Text input -->
36  <UInput v-model="email" type="email" placeholder="Email" icon="i-heroicons-envelope" />
37 
38  <!-- With validation state -->
39  <UInput v-model="email" :color="emailError ? 'error' : undefined" />
40 
41  <!-- Textarea -->
42  <UTextarea v-model="bio" placeholder="Bio" :rows="3" autoresize />
43 
44  <!-- Select -->
45  <USelect v-model="country" :options="['USA', 'Canada', 'Mexico']" placeholder="Country" />
46</template>
47```
48 
49## SelectMenu (Custom Dropdown)
50 
51```vue
52<script setup>
53const selected = ref()
54const options = [
55  { label: 'John', value: 'john', avatar: { src: '/john.png' } },
56  { label: 'Jane', value: 'jane', avatar: { src: '/jane.png' } }
57]
58</script>
59 
60<template>
61  <USelectMenu
62    v-model="selected"
63    :options="options"
64    searchable
65    clear
66    placeholder="Select user"
67  >
68    <template #option="{ option }">
69      <UAvatar v-bind="option.avatar" size="xs" />
70      <span>{{ option.label }}</span>
71    </template>
72  </USelectMenu>
73</template>
74```
75 
76### SelectMenu/InputMenu Props (v4.4+)
77 
78```vue
79<USelectMenu
80  v-model="selected"
81  :options="options"
82  clear                <!-- Add clear button (v4.4+) -->
83  :viewport-ref="ref"  <!-- For infinite scroll (v4.4+) -->
84/>
85```
86 
87## Checkbox & Radio
88 
89```vue
90<script setup>
91const agreed = ref(false)
92const plan = ref('free')
93const features = ref([])
94</script>
95 
96<template>
97  <!-- Single checkbox -->
98  <UCheckbox v-model="agreed" label="I agree to terms" description="Required" />
99 
100  <!-- Radio group -->
101  <URadioGroup
102    v-model="plan"
103    :items="[
104      { label: 'Free', value: 'free', description: '$0/mo' },
105      { label: 'Pro', value: 'pro', description: '$10/mo' }
106    ]"
107  />
108 
109  <!-- Checkbox group -->
110  <UCheckboxGroup
111    v-model="features"
112    :items="[
113      { label: 'Dark mode', value: 'dark' },
114      { label: 'Notifications', value: 'notifications' }
115    ]"
116  />
117</template>
118```
119 
120## Form Validation
121 
122Uses Standard Schema (Zod, Valibot, Yup, Joi, etc.)
123 
124### With Zod
125 
126```vue
127<script setup lang="ts">
128import { z } from 'zod'
129 
130const schema = z.object({
131  email: z.string().email('Invalid email'),
132  password: z.string().min(8, 'Min 8 characters')
133})
134 
135type Schema = z.output<typeof schema>
136 
137const state = reactive<Partial<Schema>>({
138  email: '',
139  password: ''
140})
141 
142const form = ref()
143 
144async function onSubmit() {
145  await form.value.validate()
146  // Submit logic
147}
148</script>
149 
150<template>
151  <UForm ref="form" :schema="schema" :state="state" @submit="onSubmit">
152    <UFormField name="email" label="Email">
153      <UInput v-model="state.email" type="email" />
154    </UFormField>
155 
156    <UFormField name="password" label="Password">
157      <UInput v-model="state.password" type="password" />
158    </UFormField>
159 
160    <UButton type="submit">Submit</UButton>
161  </UForm>
162</template>
163```
164 
165### With Valibot
166 
167```vue
168<script setup lang="ts">
169import * as v from 'valibot'
170 
171const schema = v.object({
172  email: v.pipe(v.string(), v.email('Invalid email')),
173  password: v.pipe(v.string(), v.minLength(8, 'Min 8 characters'))
174})
175 
176type Schema = v.InferOutput<typeof schema>
177 
178const state = reactive<Partial<Schema>>({
179  email: '',
180  password: ''
181})
182</script>
183 
184<template>
185  <UForm :schema="schema" :state="state" @submit="onSubmit">
186    <!-- Same as above -->
187  </UForm>
188</template>
189```
190 
191## UFormField Props
192 
193```vue
194<UFormField
195  name="email"              <!-- Field name (matches state key) -->
196  label="Email"             <!-- Label text -->
197  description="Your email"  <!-- Help text -->
198  hint="Optional"           <!-- Right-aligned hint -->
199  required                  <!-- Shows asterisk -->
200  :help="error?.message"    <!-- Error message -->
201>
202  <UInput v-model="state.email" />
203</UFormField>
204```
205 
206## UFieldGroup (Group Fields)
207 
208```vue
209<UFieldGroup label="Name">
210  <UInput v-model="firstName" placeholder="First" />
211  <UInput v-model="lastName" placeholder="Last" />
212</UFieldGroup>
213```
214 
215## Input States
216 
217```vue
218<!-- Disabled -->
219<UInput disabled placeholder="Disabled" />
220 
221<!-- Loading -->
222<UInput :loading="true" placeholder="Loading..." />
223 
224<!-- With icon -->
225<UInput icon="i-heroicons-magnifying-glass" placeholder="Search" />
226 
227<!-- Trailing icon -->
228<UInput trailing-icon="i-heroicons-x-mark" placeholder="Clearable" />
229```
230 
231## File Upload
232 
233```vue
234<script setup>
235const { files, open, reset } = useFileUpload()
236</script>
237 
238<template>
239  <UFileUpload v-model="files" accept="image/*" multiple :max-files="5">
240    <UButton @click="open">Upload</UButton>
241  </UFileUpload>
242</template>
243```
244 
245**Note (v4.4):** FileUpload now emits `null` when clearing files (previously emitted empty array).
246 
247## Date & Time Pickers (v4.2+)
248 
249### Date Picker
250 
251```vue
252<script setup>
253const date = ref(new Date())
254const range = ref({ start: new Date(), end: new Date() })
255</script>
256 
257<template>
258  <!-- Single date -->
259  <UInputDate v-model="date" />
260 
261  <!-- Date range -->
262  <UInputDate v-model="range" mode="range" />
263 
264  <!-- With locale -->
265  <UInputDate v-model="date" locale="es" />
266</template>
267```
268 
269### Time Picker
270 
271```vue
272<script setup>
273import { Time } from '@internationalized/date'
274 
275const time = ref(new Time(12, 0))
276</script>
277 
278<template>
279  <!-- Basic time picker -->
280  <UInputTime v-model="time" />
281 
282  <!-- 24-hour format -->
283  <UInputTime v-model="time" hour-cycle="24" />
284 
285  <!-- Custom step (minutes) -->
286  <UInputTime v-model="time" :minute-step="15" />
287</template>
288```
289 
290## Common Patterns
291 
292### Login Form
293 
294```vue
295<UForm :schema="loginSchema" :state="state" @submit="login">
296  <UFormField name="email" label="Email" required>
297    <UInput v-model="state.email" type="email" icon="i-heroicons-envelope" />
298  </UFormField>
299  <UFormField name="password" label="Password" required>
300    <UInput v-model="state.password" type="password" icon="i-heroicons-lock-closed" />
301  </UFormField>
302  <UButton type="submit" block :loading="loading">Sign in</UButton>
303</UForm>
304```
305 
306### Settings Form
307 
308```vue
309<UForm :state="settings" @submit="save">
310  <UFormField name="notifications" label="Notifications">
311    <USwitch v-model="settings.notifications" label="Enable notifications" />
312  </UFormField>
313  <UFormField name="theme" label="Theme">
314    <URadioGroup v-model="settings.theme" :items="themeOptions" />
315  </UFormField>
316  <UButton type="submit">Save</UButton>
317</UForm>
318```
319 
320## Best Practices
321 
322| Do                                | Don't                      |
323| --------------------------------- | -------------------------- |
324| Use UForm + UFormField            | Build custom form wrappers |
325| Use Standard Schema (Zod/Valibot) | Write custom validation    |
326| Use v-model on form inputs        | Manually sync form state   |
327| Use `required` prop for asterisks | Add asterisks manually     |
328| Use `description` for help text   | Use separate help elements |
329