Accessible name should match the control’s label
Description
This rule checks whether an element’s accessible name (the text announced by screen readers) is similar enough to its visible label (the text sighted users see). Exact matching is not required. Small differences – such as punctuation, case changes, extra keyboard shortcuts (e.g., Ctrl+S), or minor word variations – are allowed as long as the meaning remains clear. However, completely different or contradictory names will be reported as an accessibility issue.
Disabilities impacted
- Visual impairments: screen‑reader users depend on the accessible name. A name that differs significantly from the visible label creates confusion and misidentification of controls.
- Cognitive disabilities: consistent and predictable labeling helps users understand and interact with interface elements.
- Motor impairments: voice‑command users often speak the visible label. If the accessible name is too different, the command may fail or target the wrong element.
Why it matters
Aligning the accessible name with the visible label – without requiring exact string equality – ensures that all users can reliably identify and activate controls. The rule tolerates minor, non‑semantic differences (like trailing keyboard hints or different punctuation) while flagging real mismatches. This balance improves accessibility without penalising harmless variations.
Coding problems and solutions
Common coding problems
- Substantially different text: the visible label says
Email Address
, butaria-labelsaysYour Email
. - Missing or misleading words: the label says
Delete post
, the accessible name saysRemove item
(different actions). - Hidden text overriding the visible meaning: visible label
Save
, but accessible name includes only hidden text likeSave document as PDF
.
How to fix it
Ensure names are similar, not necessarily identical
The rule accepts minor differences. For example, these are all considered valid:
- Punctuation or case: label
Search→aria-label="Search!" - Keyboard shortcuts: label
Save→aria-label="Save Ctrl+S" - Phone number formatting: label
(555) 123-4567→aria-label="5551234567" - Word overlap >75%: label
Submit form→aria-label="Submit the form now"
<label for="email">Email Address</label>
<input type="email" id="email" aria-label="Email address (required)"><label for="email">Email Address</label>
<input type="email" id="email" aria-label="Your contact info">Do not hide essential parts of the accessible name
If you use visually hidden text (e.g., .sr-only) to extend the accessible name, it should still be semantically similar to the visible label. Avoid replacing the visible meaning entirely.
<button>
Save
<span class="sr-only">the document</span>
</button>The accessible name becomes “Save the document” – similar to the visible “Save”.
<button>
Delete
<span class="sr-only">Cancel</span>
</button>Match ARIA labels with visible labels (within reason)
When using aria-label, keep the core wording similar to the visible text.
<button aria-label="Search the site">Search</button><button aria-label="Go">Search</button>Known limitations
- Fuzzy matching thresholds: the rule uses a 75% word overlap and 60% hybrid similarity. Very short strings (1‑2 words) may still be flagged if they don’t share core terms.
- Dynamic content: if both the visible label and
aria-labelupdate together, the rule re‑evaluates automatically. Stale mismatches will be reported. - Complex widgets: for custom controls with multiple parts, ensure the computed accessible name (visible text +
aria-label/aria-labelledby) is reasonably similar to the primary visible label. - Browser & screen reader differences: the accessible name computation may vary slightly, but the rule follows the standardised algorithm. Cross‑platform testing is still recommended.
Resources
- G208: Including the text of the visible label in the accessible name
- G211: Matching the accessible name to the visible label
- Using aria-label
- Accessible Name and Description Computation
Rule
- Audit: Accessibility
- Standard: WCAG 2.1 / 2.2
- Level: A
- Success Criteria: 2.5.3 Label in Name (A), 4.1.2 Name, Role, Value (A)
- ID:
accessible-name-mismatch-element-description