Forms

Form Components

Basic Input Examples

<script setup>
const email = ref('')
const bio = ref('')
const country = ref('')
</script>

<template>
  <!-- Text input -->
  <UInput v-model="email" type="email" placeholder="Email" icon="i-heroicons-envelope" />

  <!-- With validation state -->
  <UInput v-model="email" :color="emailError ? 'error' : undefined" />

  <!-- Textarea -->
  <UTextarea v-model="bio" placeholder="Bio" :rows="3" autoresize />

  <!-- Select -->
  <USelect v-model="country" :options="['USA', 'Canada', 'Mexico']" placeholder="Country" />
</template>

SelectMenu (Custom Dropdown)

<script setup>
const selected = ref()
const options = [
  { label: 'John', value: 'john', avatar: { src: '/john.png' } },
  { label: 'Jane', value: 'jane', avatar: { src: '/jane.png' } }
]
</script>

<template>
  <USelectMenu
    v-model="selected"
    :options="options"
    searchable
    clear
    placeholder="Select user"
  >
    <template #option="{ option }">
      <UAvatar v-bind="option.avatar" size="xs" />
      <span>{{ option.label }}</span>
    </template>
  </USelectMenu>
</template>

SelectMenu/InputMenu Props (v4.4+)

<USelectMenu
  v-model="selected"
  :options="options"
  clear                <!-- Add clear button (v4.4+) -->
  :viewport-ref="ref"  <!-- For infinite scroll (v4.4+) -->
/>

Checkbox & Radio

<script setup>
const agreed = ref(false)
const plan = ref('free')
const features = ref([])
</script>

<template>
  <!-- Single checkbox -->
  <UCheckbox v-model="agreed" label="I agree to terms" description="Required" />

  <!-- Radio group -->
  <URadioGroup
    v-model="plan"
    :items="[
      { label: 'Free', value: 'free', description: '$0/mo' },
      { label: 'Pro', value: 'pro', description: '$10/mo' }
    ]"
  />

  <!-- Checkbox group -->
  <UCheckboxGroup
    v-model="features"
    :items="[
      { label: 'Dark mode', value: 'dark' },
      { label: 'Notifications', value: 'notifications' }
    ]"
  />
</template>

Form Validation

Uses Standard Schema (Zod, Valibot, Yup, Joi, etc.)

With Zod

<script setup lang="ts">
import { z } from 'zod'

const schema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Min 8 characters')
})

type Schema = z.output<typeof schema>

const state = reactive<Partial<Schema>>({
  email: '',
  password: ''
})

const form = ref()

async function onSubmit() {
  await form.value.validate()
  // Submit logic
}
</script>

<template>
  <UForm ref="form" :schema="schema" :state="state" @submit="onSubmit">
    <UFormField name="email" label="Email">
      <UInput v-model="state.email" type="email" />
    </UFormField>

    <UFormField name="password" label="Password">
      <UInput v-model="state.password" type="password" />
    </UFormField>

    <UButton type="submit">Submit</UButton>
  </UForm>
</template>

With Valibot

<script setup lang="ts">
import * as v from 'valibot'

const schema = v.object({
  email: v.pipe(v.string(), v.email('Invalid email')),
  password: v.pipe(v.string(), v.minLength(8, 'Min 8 characters'))
})

type Schema = v.InferOutput<typeof schema>

const state = reactive<Partial<Schema>>({
  email: '',
  password: ''
})
</script>

<template>
  <UForm :schema="schema" :state="state" @submit="onSubmit">
    <!-- Same as above -->
  </UForm>
</template>

UFormField Props

<UFormField
  name="email"              <!-- Field name (matches state key) -->
  label="Email"             <!-- Label text -->
  description="Your email"  <!-- Help text -->
  hint="Optional"           <!-- Right-aligned hint -->
  required                  <!-- Shows asterisk -->
  :help="error?.message"    <!-- Error message -->
>
  <UInput v-model="state.email" />
</UFormField>

UFieldGroup (Group Fields)

<UFieldGroup label="Name">
  <UInput v-model="firstName" placeholder="First" />
  <UInput v-model="lastName" placeholder="Last" />
</UFieldGroup>

Input States

<!-- Disabled -->
<UInput disabled placeholder="Disabled" />

<!-- Loading -->
<UInput :loading="true" placeholder="Loading..." />

<!-- With icon -->
<UInput icon="i-heroicons-magnifying-glass" placeholder="Search" />

<!-- Trailing icon -->
<UInput trailing-icon="i-heroicons-x-mark" placeholder="Clearable" />

File Upload

<script setup>
const { files, open, reset } = useFileUpload()
</script>

<template>
  <UFileUpload v-model="files" accept="image/*" multiple :max-files="5">
    <UButton @click="open">Upload</UButton>
  </UFileUpload>
</template>

Note (v4.4): FileUpload now emits null when clearing files (previously emitted empty array).

Date & Time Pickers (v4.2+)

Date Picker

<script setup>
const date = ref(new Date())
const range = ref({ start: new Date(), end: new Date() })
</script>

<template>
  <!-- Single date -->
  <UInputDate v-model="date" />

  <!-- Date range -->
  <UInputDate v-model="range" mode="range" />

  <!-- With locale -->
  <UInputDate v-model="date" locale="es" />
</template>

Time Picker

<script setup>
import { Time } from '@internationalized/date'

const time = ref(new Time(12, 0))
</script>

<template>
  <!-- Basic time picker -->
  <UInputTime v-model="time" />

  <!-- 24-hour format -->
  <UInputTime v-model="time" hour-cycle="24" />

  <!-- Custom step (minutes) -->
  <UInputTime v-model="time" :minute-step="15" />
</template>

Common Patterns

Login Form

<UForm :schema="loginSchema" :state="state" @submit="login">
  <UFormField name="email" label="Email" required>
    <UInput v-model="state.email" type="email" icon="i-heroicons-envelope" />
  </UFormField>
  <UFormField name="password" label="Password" required>
    <UInput v-model="state.password" type="password" icon="i-heroicons-lock-closed" />
  </UFormField>
  <UButton type="submit" block :loading="loading">Sign in</UButton>
</UForm>

Settings Form

<UForm :state="settings" @submit="save">
  <UFormField name="notifications" label="Notifications">
    <USwitch v-model="settings.notifications" label="Enable notifications" />
  </UFormField>
  <UFormField name="theme" label="Theme">
    <URadioGroup v-model="settings.theme" :items="themeOptions" />
  </UFormField>
  <UButton type="submit">Save</UButton>
</UForm>

Best Practices