Form

Schema-validated fields, composed from Form and FormField.

Composing a form

A form is two components. Form owns validation and submission: a Zod schema plus a reactive state object, with no field UI of its own. FormField wraps one control with its label, optional description or hint, and validation error. Every field's name must match a key in the schema and state; that is what routes an error to the right FormField.

A basic form

1<template>2  <Form :schema="schema" :state="state" @submit="onSubmit">3    <FormField label="Email" name="email">4      <Input v-model="state.email" placeholder="you@example.com" class="w-full" />5    </FormField>6    <Button html-type="submit" class="self-start">Submit</Button>7  </Form>8</template>

Field types

Every control, one schema

1<template>2  <Form :schema="schema" :state="state" @submit="onSubmit">3    <FormField label="Name" name="name">4      <Input v-model="state.name" placeholder="Jane Doe" class="w-full" />5    </FormField>6    <FormField label="Bio" name="bio">7      <Textarea v-model="state.bio" :rows="3" class="w-full" />8    </FormField>9    <FormField label="Role" name="role">10      <Select v-model="state.role" :items="roleOptions" class="w-full" />11    </FormField>12    <FormField label="Seats" name="seats">13      <InputNumber v-model="state.seats" :min="1" :step="1" class="w-32" />14    </FormField>15    <FormField label="Plan" name="plan">16      <RadioGroup v-model="state.plan" :items="planOptions" />17    </FormField>18    <FormField name="notify">19      <Switch v-model="state.notify" label="Email notifications" />20    </FormField>21    <Button html-type="submit">Submit</Button>22  </Form>23</template>

Validating and submitting

The schema drives field-level errors, routed by name.
A trigger outside the <Form> element, such as a drawer or dialog footer, calls formRef.value?.validate() from a template ref. See the drawer example below.
Enter submits only when the form has a submit button (html-type="submit").
Form has no submitting state. The submit button's loading prop is toggled around the async handler.

Examples

Full page composition

A settings form inside a PageSection and a Card, with the submit button inside the form and its loading prop toggled around the async handler.

Profile

Your name and contact email.

1<template>2  <PageSection title="Profile" description="Your name and contact email.">3    <Card>4      <Form :schema="schema" :state="state" class="flex flex-col gap-4" @submit="onSubmit">5        <FormField label="Display name" name="displayName">6          <Input v-model="state.displayName" class="w-full" />7        </FormField>8        <FormField label="Email" name="email">9          <Input v-model="state.email" class="w-full" />10        </FormField>11        <Button html-type="submit" :loading="saving" class="self-start">Save</Button>12      </Form>13    </Card>14  </PageSection>15</template>

Drawer footer triggers the form

The footer stays fixed while the body scrolls, so its Save button sits outside the Form element and calls formRef.value?.validate().

1<template>2  <Drawer v-model:open="open" title="New automation">3    <Form ref="formRef" :schema="schema" :state="state" class="flex flex-col gap-4">4      <FormField label="Title" name="title">5        <Input v-model="state.title" class="w-full" />6      </FormField>7      <FormField label="Description" name="description">8        <Textarea v-model="state.description" :rows="3" class="w-full" />9      </FormField>10      <FormField label="Trigger" name="trigger">11        <Select v-model="state.trigger" :items="triggerOptions" class="w-full" />12      </FormField>13      <FormField name="enabled">14        <Switch v-model="state.enabled" label="Enabled" />15      </FormField>16    </Form>17    <template #footer>18      <Button variant="outline" @click="open = false">Cancel</Button>19      <Button :loading="saving" @click="onSave">Save</Button>20    </template>21  </Drawer>22</template>

Props

Name	Type	Default
schema	ZodSchema \| ...	-
state	object	-
...props	UForm props (validate, validateOn, disabled, name, nested, transform, id, ...)	-

Slots

Name	Description
default	Form fields, scoped with `errors` and `loading`.

Guidelines

Do

Give every field a name that matches its key in schema and state.
Wrap every control in a FormField, including a Switch or Checkbox that carries its own label.
Include a submit button with html-type="submit" so that Enter submits the form.

Call formRef.value?.validate() from a template ref when the trigger sits outside the <Form> element.

Don't

Don't validate with watch or per-field checks when the schema already expresses the rule.
Don't track a submitting state in Form; toggle the submit button's loading prop instead.
Don't build a form from bare controls without Form; validation and error routing only work through it.