Form field
Every field has a visible label, room to type, and an error that says how to fix the problem.
Show code
<div class="field">
<label for="email">Email</label>
<input class="box" type="email" id="email" name="email"
autocomplete="email" aria-describedby="email-error"
aria-invalid="true" required>
<p id="email-error">Enter an email address, like name@company.com.</p>
</div> When to use it
- For every question a form asks: a label above, the field, a hint when the format isn’t obvious, and the error under it when there is one.
- Fields for text, email, phone, numbers, longer writing, a drop-down with one choice, and a tickbox for a single yes.
Use something else when:
- One whole thing is turned on or off: a Switch.
- Someone is choosing a day near today: a Date field.
- Several choices can be on together in a filter: a Multi-choice drop-down.
Anatomy
- Label: always visible, above the field, tied to it with
for. Optional fields say "(optional)"; required ones don't need a mark. - Input: 1 px border, the field corner (
shape.field: 8 px, 3 px in Gulo), the page colour inside so it reads as a hole in the card. - Hint: why we're asking, or the format. Linked with
aria-describedby. - Error: replaces the hint, in the theme-aware error colour, and the border turns the same colour.
Validation
- Check when someone leaves a field or submits, never while they're still typing.
- On submit, show a summary panel at the top listing each problem, and move focus to it.
- Keep what people typed. Never clear a form because one field is wrong.
- The form works without JavaScript: it posts normally to the form service.
What is built today: the contact form writes each problem under its field, ties the message to the field so a screen reader reads them together, moves to the first field with a problem, keeps what was typed and works without JavaScript. Not built yet: the summary at the top, and checking a field when someone leaves it. The component checks say the same.
See Forms and validation for the full flow.
Do and don't
Do
- Ask only for what you'll use
- Use the right input type (
email,tel) - Write errors as instructions
Don't
- Use placeholder text as a label
- Split names into first and last unless you must
- Write "Invalid input" or "Error"
Accessibility
What it does for you
- A visible label above every field, tied to it with
for, so a click on the label goes to the field and a screen reader says the label. - Hints and the place an error is written are tied to the field with
aria-describedby, so both are read with it. - A field with a problem is marked
aria-invalid, its border and message take the error colour, and the message is words, so nothing is told by colour alone. - No spell check, capitals or autocorrect on fields that aren’t sentences (email, web address, phone, number).
- Text in a field is 16px on a phone, so iPhones don’t zoom the page in.
What you need to do
- A label that says what to type. Never a placeholder in its place: it vanishes as soon as someone types.
autocompleteon anything about the person (name, email, phone, organisation), so the browser can fill it.- The right
type(email,tel), so a phone shows the right keyboard. - An error written as what to do ("Enter an email address, like name@company.com"), not "Invalid input".
- Say which fields are optional. Don’t mark the required ones.
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves to the field, in the order the fields are written. |
| Typing | Goes into the field. Nothing is checked while you type. |
What a screen reader is told
- Name: the label. Role: the kind of field (edit text, checkbox, combo box for a drop-down).
- Description: the hint, then the error once there is one. State: invalid when marked, required when it is.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 1.3.1 Info and Relationships | A | Label, hint and error are each tied to the field in the markup, not only placed near it. |
| 1.3.5 Identify Input Purpose | AA | Fields about the person carry autocomplete, where the page sets it. |
| 1.4.1 Use of Color | A | An error is a sentence under the field; the colour only backs it up. |
| 1.4.3 Contrast (Minimum) | AA | Error text is at least 5.3:1 against the field’s card in every theme. |
| 3.3.1 Error Identification | A | The field with the problem is marked and its message says what is wrong. |
| 3.3.2 Labels or Instructions | A | Every field has a visible label, and a hint where the format isn’t obvious. |
| 4.1.2 Name, Role, Value | A | Native inputs, with their names, descriptions and states from the markup. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 6 of 6 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 6 checks made with the keyboard, on the example at the top of this page:
- Passed Each field is named by its visible label
- Passed A click on a label moves to its field
- Passed The hint is tied to its field, so it is read with it
- Passed The field with a problem is reported invalid, and its message is tied to it
- Passed Tab goes through the fields in the order they are written
- Passed The error text has at least 4.5:1 against its background
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- The two rules this page asks for and the contact form doesn’t yet follow: a summary of problems at the top after sending, and checking a field when someone leaves it.
Evidence
Where it's used
| Where | For |
|---|---|
| Every form on every site | The contact and enquiry forms, the newsletter sign-up, Headland’s yacht search. |
| Somnia CMS | Every form in the editor and its settings pages. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| Search boxes had autocorrect, spell check and capitals on, as any text field does. | Switched off for search boxes (1.35.0), and on 16 November for email, web address, phone and number fields. | |
| A tickbox and its label lost their gap outside a field. | Tickbox rows lay out on their own (1.42.0). | |
| Writing this page’s accessibility section showed an error message was only placed under its field, not tied to it, so a screen reader would not read it with the field. | The contact form ties each message to its field and moves to the first field with a problem (1.81.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- GOV.UK Design System: Text input: Labels above fields, hints tied to them, no placeholder as a label, and errors written as what to do.
- W3C: Forms tutorial, labelling controls: A visible label tied to its field.
What we don't know yet
- No one has been watched filling in a form on these sites.
- An error summary and checking on leaving a field are described here and on the Forms pattern but not built.