form-control-label-quality
Form field labels should be descriptive and distinguishable
Flags a visible form-field label that is a placeholder ("Label", "Field"), or that repeats another field's label with no visible context (heading, legend, or row) telling the two apart. English placeholders are always recognized, and German, Spanish, French or Japanese ones when the field is in that language.
Applies to. Visible form fields: native input (excluding hidden and the button-like types), select, textarea, or an element with one of the ARIA widget roles ACT cc0f0a lists (checkbox, combobox, listbox, menuitemcheckbox, menuitemradio, radio, searchbox, slider, spinbutton, switch, textbox; the first real role token of the role attribute, in any case) that carry a visible programmatic label: a <label> association, or the elements aria-labelledby points at. A field named only by aria-label/title has no visible label to judge and is out of scope here (its labelling mechanism is form-control-programmatic-label-quality's concern, its presence form-control-programmatic-label-present's). A custom element whose ElementInternals give it one of those roles (this.attachInternals().role), with no role attribute naming another, counts as a native element with that role does. Finding nothing to ask about, it reports notApplicable, not pass: it applies only to what its check flags, and finding nothing there doesn't show that all is well.
Expectation. The visible label text (a) is not a placeholder left in the markup ("label", "field", "enter text", ...), (b) is not shared with another field that no visible context tells apart (the same "Name" twice, with nothing visible on screen saying which is shipping and which is billing), and (c) is the whole of the field's programmatic label, not the visible fragment of a label whose descriptive part is hidden.
What a finding reports.
label: the visible label text of the field.sharedWith: how many other fields have the same label with nothing visible telling them apart, a count. 0 when no other field shares it.hiddenLabelParts: how many parts of the field's label are hidden from sight, a count. 0 when the whole label is visible.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<label>Label <input type="text" name="f1"></label>
The label text is the placeholder word "Label" itself, not a real description of the field.
<label for="e">Email address:</label><input id="e" type="text">
The label text is a genuine, descriptive name for the field.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
DUPLICATE_LABEL_TEXT
- Find the field the report names and the other fields with the same visible label.
- Look at the screen around each one: a legend, heading, row text or nearby text that says which is which.
- Decide whether the fields ask for the same thing (a repeated search box) or different things (shipping and billing name).
Pass. The fields serve the same purpose, or something visible near each one makes clear which is which.
Fail. Different fields share a label and nothing visible tells them apart, so a user cannot tell which to fill in, which fails WCAG 2.4.6 (G131).
PARTIALLY_HIDDEN_LABEL
- Find the field the report names and read its visible label on screen.
- Inspect the field in the Accessibility pane and read its full computed name, including the hidden parts.
- Look at what is visible around the field, such as a group title, a heading, or the row or column it sits in, which can give the hidden part its meaning.
- Ask whether the visible label, read with what is visible around it, tells a sighted user what to enter or choose.
Pass. The visible part of the label, alone or with what is visible around it, describes the field; the hidden part only adds detail.
Fail. Neither the visible part of the label nor anything visible around it identifies the field without the hidden part (for example, only "Go" is shown), which fails WCAG 2.4.6 (ACT cc0f0a).
PLACEHOLDER_LABEL_TEXT
- Find the field the report names and read its visible label.
- Work out from the page what the field is for.
- Decide whether the label says that, or is template text such as "Label", "Field" or "Enter text".
Pass. The label is a real name for what the field asks for in this context (for example "Value" in a key/value editor).
Fail. The label is placeholder text that does not say what the field is for, which fails WCAG 2.4.6 (G131).