Form
FreeSend a group of fields in one go: check them, show what is wrong, save and confirm.
npx wunderui-cli add formPlayground
Installation
npx wunderui-cli add formWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Form } from "@/components/ui/form"Then use it:
import { Button } from "@/components/ui/button"
import { Field, FieldError, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
export function Subscribe() {
return (
<Form onFormSubmit={(values) => console.log(values)}>
<Field name="email">
<FieldLabel>Work email</FieldLabel>
<Input type="email" required placeholder="name@company.com" />
<FieldError match="valueMissing">Enter your work email address.</FieldError>
<FieldError match="typeMismatch">Enter an email address like name@company.com.</FieldError>
</Field>
<Button type="submit" variant="gradient">
Subscribe
</Button>
</Form>
)
}Expected result: You see a label, a white field and a Subscribe button. With the field empty, pressing it turns the field red and shows its message; with an address, the form sends.
When to use
Use Form for
- A group of fields that are sent together, such as a profile, an address or a payment
- A form that has to check its fields, show what is wrong and say when it has saved
- A form whose rules only the server knows, such as a name that is already taken
States
A form is always in one of a few states, each with its own message and button state. Every card is a live form, so edit a field, press Save or Cancel and watch it move to the next state.
Validation mode
The mode says when a field is checked. On submit waits for the first Save and then re-checks as the person types, on blur checks when a field is left, and on change checks on every keystroke.
Errors
An error belongs next to its field. A summary on top helps in a long form, a system error says what the person cannot fix themselves, and entries are always kept.
Layout
One column is the default and reads fastest. Two columns pair short related fields, settings rows put label and hint left and the control right, and all fall back to one column on a narrow screen.
Keyboard interactions
A form adds no keys of its own. Keyboard behaviour comes from the order of its controls and the browser's implicit submit.
- TaborShift+Tab
- Moves through the fields and buttons in the order they are written. A disabled button is skipped; a pending button stays in the order.
- Enter
- In a text field, sends the form through its submit button. If a field is invalid, focus goes to the first one and its message shows. In a textarea it starts a new line.
- SpaceorEnter
- On a focused button, presses it. On the summary lines, moves focus to the field that is named.
Behavior and motion
What the form does itself, and what it leaves to the page.
- A native form
- Form renders a native form element, so action, method and onSubmit all work. It turns off the browser's own validation bubbles so fields show their own messages.
- Submit
- The submit handler runs when every field is valid and gets an object with the value of each named field. It also stops the page from reloading, so name every Field: the name is the key.
- When fields are checked
- Validation mode sets when fields are checked: on submit (default, then re-checks as the person types), on blur, or on every change. A Field can set its own mode.
- Errors from outside
- Pass server errors as field names and messages, and the matching Field turns invalid and shows its message. Clear it when the person edits the field, or the red state stays.
- Focus after a failed send
- After a failed send, focus moves to the first invalid field in page order, and that field is marked invalid. If you check fields yourself, move focus the same way.
- Pending and success
- While the send runs, the main Button is pending: it keeps its place, shows a spinner and ignores presses, and the way out is disabled. When it ends, show the result in an Alert and the status line.
- Pristine and unsaved
- A form with nothing to send, like a settings form without changes, may keep Save disabled. Once a field differs from what is saved, the status line says unsaved and Save is available.
- Status messages
- The status line is a polite live region: changes are announced after the current speech and never take focus. The error summary is an alert and is announced at once.
- Motion
- The form doesn't move. Field borders change colour quickly and the spinner in a pending button turns.
- Reduced motion
- With reduced motion, border colours still change as a short fade and spinners stop turning. The pending label still says what is happening.
Anatomy
Form sends a group of fields together. The fields, error summary, status line and actions are parts you compose; Form owns the submit and hands errors to the right field.
- 1data-slot="form"
A vertical stack with 20 px between children. It turns off browser validation bubbles, submits the named field values when all fields are valid, and focuses the first invalid one.
- 2data-slot="form-error-summary"Optional
An Alert above the fields with the error count and one line per field that moves focus to it. Add it to long forms where an error can be out of sight; screen readers announce it.
- 3data-slot="field"
One labelled control with its helper and error line. Its name joins it to the submitted values and to server errors; the error shows under the control and the helper line stays.
- 4data-slot="form-status"Optional
One line of 12 px text above the actions that says what the form is doing: checking, saving, saved or unsaved. Screen readers announce changes politely, without taking focus.
- 5data-slot="form-actions"
The row of buttons at the end, built with FormActions. The submit button sends the form, and so does Enter in a text field.
Best practices
- Do
Give every Field a name and handle the send in the submit handler. It gets the values by name and only runs when every field is valid, so Enter and the Save button take the same path.
- Do
Say what to do in the message: Enter a work email address, like name@company.com, not Invalid input. Show it under the field and keep what the person typed.
- Do
After a failed send, move focus to the first invalid field, and add an error summary to long forms. The summary jumps to each field and never replaces the message at the field.
- Do
Show the work: a pending Save with its own label (Saving…), the way out disabled, and a confirmation when done. Say All changes saved in the status line, not only with colour.
- Do
Keep the default: validate on submit, then re-check as the person corrects. Validate on blur for fields that are costly to get wrong, such as an address.
- Don’t
Don't disable the submit button to flag an invalid form, since it gives no reason. Let the person press it and tell them what is wrong; disable it only when there is nothing to send.
- Don’t
Don't clear the fields after an error or a server failure. Name the problem, keep the entries and offer Try again.
- Don’t
Don't run the check from a click handler on the submit button. Use the submit handler so keyboard and mouse users take the same path.
API reference
Form renders a native form element and takes all its attributes plus a ref. The table lists the props the library adds; Field, Fieldset and Form Actions have their own pages.
A vertical stack with 20 px between children. It turns off browser validation bubbles, submits the named field values when all fields are valid, and focuses the first invalid one.
| Prop | Type | Default | Description |
|---|---|---|---|
| onFormSubmit | (values, details) => void | — | Called with the values of the named fields when every field is valid. is an object keyed by the of each Field. It stops the page from reloading for you. is the submit event. |
| errors | Record<string, string | string[]> | — | Errors that come from outside, usually from a server after a send. The keys are Field names and the values are the message or messages. The Field with that name turns invalid and its shows the message. Clear it when the person edits the field. |
| validationMode | "onBlur" | "onChange" | "onSubmit" | "onSubmit" | When the fields are checked. (the default) checks at the first send and re-checks as the person types afterwards, checks when a field loses focus and checks on every change. The of a Field takes precedence. |
| actionsRef | RefObject<Form.Actions | null> | — | A ref to imperative actions. checks every field and checks one, for example before the next step of a wizard. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("form")npx wunderui-cli add formThe full library index for assistants is at /llms.txt.