Form patterns

Recipes for real forms, built from Field, Input, Select, Checkbox, Switch and Button. None is a new component: copy one into your app and name it for your domain.


Fields

One field is a label, a control and a line under it: help text, or an error after validating on blur or submit.

A field and its line

Help text sets expectations before typing. An error shows after validating, with the red border.

Shown on your public profile.

Enter a valid email address.

All parts

What each part does. The gaps between them are on the Spacing page.

PartUse
FieldHolds one field and sets its gaps: 8px label to control, 8px control to help. invalid marks the control and shows the error
FieldLabelThe label. optional adds a quiet "Optional", so required stays the silent default
FieldDescriptionHelp text under the control that sets expectations
FieldErrorThe error, shown only when the field is invalid. It always travels with the red border: color alone is not an error
Input, Textarea, SelectThe control. A trigger has no caret, so its focus border is stronger than a text field's

States

Disabled fades to 70% on the muted fill and is skipped by Tab. Read-only takes the same fill at full strength and can still be focused and copied, so use it for an API key or a generated URL.

Default. Hover darkens the border, focus darkens it again.

Read-only. Full strength, still focusable and copyable.

Disabled. Faded, skipped by Tab, and cannot be copied.

Sizes

Input takes Button's size names and radius, so a field and a button of one size line up in a row. On phones the text is 16px so iOS does not zoom; it steps down at md.


Layouts

How fields sit together: a setting beside its control, fields sharing a row, and a form ending in its actions.

Setting rows

Label and description on one side, control on the other. The whole row is the target, not just the control, so there are no dead zones.

Grouped fields

Related fields share a row and stack on narrow screens. Two fields side by side are still field to field, so the row gap is the field gap.

A form ends in an action row. The primary action sits on the right. Cancel stays at the far left, apart from the choices, as in Dialog and Sheet footers.


Submitting

What a form does while it sends, and the one-field forms that only ask for an email.

While it sends

Set the submit button to loading and disable the fields while the request runs. The button keeps its width, shows a spinner after 200ms and tells screen readers it is busy, so nothing jumps and nothing submits twice.

One-field forms

One field and one button, for an email or a search. Stacked works at any width. Inline puts the button on the field's row, and its label can do the persuading. An icon stands in for the label when the ask is plain; the label stays for screen readers.

No spam. Unsubscribe anytime.