Form
Validation and submission built from parts that wire values, labels, hints and errors to any Vitral control, with rules or a schema.
Import
import { Form } from '@vitral/vue';Sign-up
Built-in rules on each field. Nothing is checked until the first submit; after that each field is checked again as it changes, so a fixed error goes away at once.
Validate on blur or on submit
`validate-on` says when a field is first checked: `submit` (the default), `blur`, `change` or `input`. Checking on blur tells people early; checking on submit never interrupts them. A field can choose its own.
Rules cover a field at a time; a schema covers the form. @vitral/forms ships adapters for Zod, Yup, Valibot, Superstruct and anything carrying ~standard (ArkType, Effect Schema), each written against the smallest shape its library exposes, so the package depends on none of them — the whole of it is documented here, including the same form without a framework.
With a resolver
A resolver validates every value at once: `zodResolver(schema)`, `yupResolver`, `valibotResolver`, `superstructResolver`, `standardSchemaResolver` or `functionResolver`, on `Form.Root` or on `createForm`. An adapter only needs the shape of the schema — `safeParse`, `validate`, `~standard` — so no schema library is installed here and the one below is written by hand. Cross-field checks (the years) and transforms (the handle is trimmed and lower-cased on submit) come from the schema, and what it transforms is what is submitted.
Async validation
A rule may return a promise. Here the name is checked as you type, 300 ms after the last keystroke; a newer check aborts the one still running (its `signal` fires), so a slow answer never overwrites a fresh one. Try “ada” or “admin”.
Field arrays
`Form.FieldArray` repeats a group: each entry has a stable key and a path to name its fields by, and the slot can append, insert, remove, move and swap. Errors move with their rows. Rules on the list itself show in a `Form.Message` placed directly inside.
Error summary
`Form.Summary` (also `Form.Errors`) appears after a failed submit, above the form: an alert listing every error as a link to its field, which takes focus so a keyboard or screen reader user starts there. The fields’ own messages stay silent meanwhile, so nothing is announced twice.
Every control
One of each Vitral input, each bound by nothing more than being placed inside a `Form.Field`. Submit the empty form to see every one of them invalid.
Using the form without a framework
The state, the rules and the async checks are @vitral/forms, which draws nothing and imports no framework; the Form parts are a wrapper over it. createForm() holds the values and the errors, register() says what a field is called and what it has to be, and subscribe() reports every change. The one below binds it to three plain inputs by hand — which is all a React or an Angular adapter would do; its code shows how.
API
Read from packages/vue/src/components/Form/types.ts, so it says what the component actually accepts.
Props
| Name | Type | Description |
|---|---|---|
| initialValues | FormValuesLike | The values to start from, and to go back to on reset. Defaults to a copy of v-model. |
| resolver | FormResolverLike | Validates the whole form: `zodResolver(schema)`, `yupResolver(schema)`, `functionResolver(fn)`… |
| validate | (values: FormValuesLike, context: { signal: AbortSignal }) => unknown | Checks across fields, beside the resolver: return messages by path. |
| rules | Record<string, FormRuleLike | FormRuleLike[]> | Rules by path, for a form that declares them in one place. |
| validateOn | FormValidateOn | FormValidateOn[] | When a field is first validated. Defaults to `submit`. A field can say otherwise. |
| revalidateOn | FormValidateOn | FormValidateOn[] | When a field that has been validated is validated again. Defaults to `input`, so an error clears as it is fixed. |
| debounce | number | Milliseconds to wait after typing stops before an input-triggered validation. |
| form | object | A form made with `useForm()`, to drive it from outside the template. |
| focusOnInvalid | boolean | After a failed submit, move focus to the error summary (when there is one) or to the first invalid field. Defaults to true. |
| disabled | boolean | Disables every control wired by a field, and the submit button. |
| errorRelation | FormErrorRelation | How a control points at its error. Defaults to `both`. |
Plus pt, dt and unstyled from BaseProps, see pass-through and unstyled mode.
Emits
| Event | Payload | Description |
|---|---|---|
| submit | event: FormSubmitEvent | Every submit, with its values and whether they are valid. A handler returning a promise keeps the form submitting until it settles. |
| invalid-submit | event: FormInvalidSubmitEvent | A submit stopped by errors. |
| reset | event: FormResetEvent | — |
Slots
| Name | Slot props | Description |
|---|---|---|
| default | (props: FormRootSlotProps) | — |