Forms
How to build forms with Form and Field. Visible labels, descriptions before errors, when to validate, the error summary, focus, buttons and optional fields.
A form is a conversation where the reader does most of the talking. Your job is to ask clearly, wait until they are done, and when something is wrong, say so once, in the right place, in words they can act on. Form and Field already do most of the mechanics. These are the decisions they leave to you.
Here is a form that follows every rule on this page. Submit it empty, then fix one field and leave it:
Structure
- One column. Readers go down a form, not across it. Two fields side by side only work when they belong together, like first and last name or a card's expiry and CVC.
- Wrap the form in
Formand each input inForm.Field. UseField.Groupfor spacing andField.Setwith aField.Legendfor related controls like a group of radios. - Ask only for what you need now. Every field you remove is one the reader cannot get wrong.
Labels stay visible
Every control has a visible label above it, through
Field.Label. A placeholder is not a label: it disappears the moment the reader starts typing, it is usually too faint to read, and screen readers treat it inconsistently.Description before error
The order inside a field is label, control, description, error. The description is permanent help: what the field is for, what format it takes. The error is temporary and comes last, so when it appears it does not push the help out of the way, and screen readers read the hint before the problem.
Write descriptions that prevent errors, not ones that repeat the label. "Lowercase letters, numbers and dashes" saves a round trip. "Enter your project name" under a field called Project name does not.
When to validate
Validate when the reader says they are done, not while they are still typing.
- On submit. That is the default in
Form. Nobody sees an error for a field they have not finished. - Then on blur. After a failed submit, each field checks itself again when the reader leaves it, so errors clear as they get fixed.
Formdoes this for you. - Never on every keystroke. Telling someone their email is invalid after they typed "a" is rude and useless.
validationMode="onChange"exists for live helpers like a character count, not for errors.
Do not disable the submit button until the form is valid. A disabled button cannot explain itself, and the reader is left guessing which field is the problem. Let them submit and show them.
Error summary and focus
On any form longer than a few fields, put
Form.ErrorSummary at the top. After a failed submit it lists every problem, each one a link that moves focus to its field. At the same time, focus jumps to the first invalid field, so keyboard and screen reader users land right on the problem.Errors from the server work the same way: pass them to
errors, keyed by field name, and they show up in the field and in the summary. A field drops its server error as soon as the reader edits it.The messages themselves follow the writing guidelines: what went wrong and how to fix it, in the reader's terms.
Buttons
A form has one primary action. Everything else is secondary, outline or ghost.
- The primary button repeats the purpose of the form with a verb and an object: "Create project", "Send invites", "Save changes". The reader should know what happens before they click.
- Cancel goes to the left of the primary action, both aligned to the end, the same as
Dialog.FooterandAlertDialog.Footer. On narrow screens the footer stacks and the primary action goes on top. In right to left layouts the order mirrors. - Use
Form.Submitfor the primary button. It shows the loading state while the action runs and ignores extra clicks, so nothing is submitted twice.
Invite 3 people to Northwind?
They get an email with a link that works for 7 days.
Invite 3 people to Northwind?
They get an email with a link that works for 7 days.
Required and optional
Mark the exception, not the rule. Most forms ask for things they need, so label the few optional fields with "(optional)" and leave the required ones plain. If most fields are optional, flip it and mark the required ones in words.
- Put
requiredon the control itself, not only in the label.Formuses it to validate and assistive tech reads it out. - Avoid a lone red asterisk. It needs a legend to mean anything, and color alone does not say "required" to everyone.
- If a field is optional, ask whether it needs to be there at all.
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.