field

A field puts a label, a hint and an error around one control, one under the other. It connects them to the control, so assistive technology reads them together.

when to use

• Around every input, select and textarea in a form. They have no label of their own, so the field gives them one.
• Around a checkbox or a switch, only to add a hint or an error. Their own label already names them.
• Whenever a value can be wrong. The field shows the error in place of the hint, and marks the control as invalid.

when to use something else

• To label a group of checkboxes, switches or radio buttons. A field labels one control. Put the group in the browser's own group frame, with a title for the whole group; forms and settings shows how.
• Where a visible label doesn't fit, such as a search box in a toolbar. Use an input with a search icon in front and a name that is read out but not shown, or use the filter bar.
• For a message about the whole form, such as “Could not save”. Use a banner above the form, as message handling explains.

anatomy

1. Column. The parts, one under the other, with a little space between them.
2. Label (optional). What the value is, in the body face. It is shown just as it is written, in sentence case.
3. Required marker (optional). A blue asterisk after the label. Assistive technology doesn't see it.
4. Control. The one control the field labels: an input, a select, a textarea, a checkbox or a switch.
5. Message (optional). The hint, in a dim colour, or the error, in red, both in small body text. The error takes the hint's place.

variants and states

A field can carry a hint, be marked as required, or show an error. The error takes the hint's place, and it turns the border of an input, a select or a textarea red.

The same parts work around every control. Around a checkbox, leave the field's label out and keep the hint: the checkbox already names itself.

Marking a field as required only draws the asterisk. Make the control itself required as well, as this select is, so that the browser and assistive technology know.

behaviour

• The field adds no keys and no tab stop of its own. tab goes straight to the control, and the control keeps its own keys.
• A click on the label puts focus in the control, or turns a checkbox or a switch on or off.

The full keyboard map is on the field's React page.

accessibility

• The label's text is the control's accessible name. Nothing changes its letters, so write the label exactly as it should be read, in sentence case.
• A screen reader reads the hint or the error after the control's name and its value.
• With an error, the control is marked as invalid for assistive technology too, not only by its red border.
• Around a checkbox or a switch, leave the field's label out. Two labels would name the control twice.

Today:

• The asterisk is only drawn, and assistive technology doesn't see it: the field doesn't make the control required. Make the control required itself, and say once per form what the asterisk means.
• An error isn't announced when it appears. When people send a form that has errors, move focus to the first invalid control, so its error is read out; see message handling.
• An error around a checkbox or a switch doesn't mark the box. It keeps its normal look, and the error text is the only sign.

content

• Label. A noun phrase for the value, in sentence case, with no colon: “Release name”, “Region”, “Timeout (ms)”.
• Hint. What is accepted and why, in one line: “Lowercase letters, digits and hyphens”. Don't repeat the label.
• Error. What is wrong and how to fix it: “Use 63 characters or fewer”. No blame, no codes, and no “Invalid input”. The error takes the hint's place, so repeat the rule when people still need it.
• Required. Mark the required fields, and explain the asterisk once, at the top of the form. When most fields are required, mark the optional ones in their label instead: “Description (optional)”.

do and don't

related

• Input: the control a field wraps most often.
• Select: a value from a known list, labelled by a field.
• Forms and settings: how fields stack into a form, with groups and a save button.
• Message handling: errors on fields, next to the messages about the whole form.

specs

• Wiring: the control's id is htmlFor when you pass it, else the child's own id, else a generated one. The label points at it, and the hint or the error joins the control's aria-describedby, so it is read after the name and the value.
• Announcing: the message is not a live region, so an error that appears isn't announced.
• Groups: a group of checkboxes, switches or radios is a native <fieldset> with a <legend>, not a field.
• No room for a label: an Input with an aria-label and a leading search icon.
• Keyboard: no keys and no tab stop of its own.