Form
Form state on top of Field. Native and zod validation, an error summary, server errors and a pending submit button.
NewInstallation
Copy and paste the following code into your project.
Update the import paths to match your project structure.
Anatomy
Composition
Use the following composition to build a
Form:Form does not replace Field. Form.Field is a Field that knows its name: it gives the control that name, marks it invalid and fills Field.Error with the messages for that name. Everything else about Field works the same.How validation works
The form renders with
noValidate, so the browser never shows its own bubbles. On submit:- Every named control runs the browser's constraint checks (
required,type="email",minLength,patternand so on) and itsvalidationMessagebecomes the error. - If you pass a
schema, the form data goes throughschema.safeParse. Repeated keys arrive as arrays. Issues are matched to fields by their path joined with dots, soaddress.citylands on<Form.Field name="address.city">. When both report the same field, the schema message wins, since it is the copy you wrote. - If anything failed, the submit is cancelled,
Form.ErrorSummarylists the problems and focus moves to the first invalid field. - If everything passed, an
actionruns as usual andonSubmitis called with the data, parsed by the schema when there is one.
After a failed submit each field checks itself again when it loses focus, so errors clear as people fix them. Typing never triggers validation unless you ask for
validationMode="onChange". Resetting the form clears every error.Any validation library with a zod style
safeParse works. Zod is not imported by the component.Variants
Server errors
Pass what your action returns to
errors, keyed by field name. Server errors show in the field and in the summary like client ones, focus moves to the first of them, and a field drops its server error as soon as someone edits it.Select and other custom controls
Controls that keep their value in a hidden input, like
Select, take the name themselves. Wrap only the trigger in Field.Control so the label points at it:Without an action
With only
onSubmit, the form prevents the browser navigation for you and calls onSubmit(data, event). If it returns a promise, Form.Submit stays busy until it settles.Keyboard
| Key | Action |
|---|---|
Enter | Submits from a text field, like any HTML form |
Tab | Moves through the fields and the summary links |
Enter | On a summary link, moves focus to the field it names |
Accessibility
- Invalid controls get
aria-invalidand theiraria-describedbypoints at the error text. Form.ErrorSummaryis an alert named by its title. Each entry is a link to the field, and following it moves focus there.- Focus goes to the first invalid field in document order after a failed submit or when server errors arrive.
Form.Submitsetsaria-busywhile an action or an asynconSubmitis pending and ignores extra clicks.
API Reference
Form
Accepts every
form attribute.| Prop | Type | Default | Description |
|---|---|---|---|
schema | { safeParse(data) } | - | Schema checked on submit, for example a zod object |
action | string | (formData: FormData) => void | - | Form action. It only runs when validation passes |
onSubmit | (data, event) => void | Promise<unknown> | - | Called with the data when validation passes |
errors | Record<string, string | string[]> | - | Errors from the server, keyed by field name |
validationMode | 'onSubmit' | 'onBlur' | 'onChange' | 'onSubmit' | When fields check themselves before the first submit |
Form.Field
Accepts every
Field prop.| Prop | Type | Default | Description |
|---|---|---|---|
name | string | - | Field name. Errors and the control use it |
Form.ErrorSummary
| Prop | Type | Default | Description |
|---|---|---|---|
title | ReactNode | "Check these fields" | Heading of the summary |
className | string | - | Additional CSS classes |
Form.Submit
Accepts every
Button prop. It is a type="submit" button that shows the loading state while the form is pending.useFormField(name)
Returns
{ name, errors, invalid } for one field. Use it for controls that need the errors directly.useFormContext()
Returns
errors, submitted, submitting, getErrors(name), focusField(name) and validate().Found something to improve?
Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.