Ensure that elements labelled through their content must have their visible text as part of their accessible name
Rule ID: label-content-name-mismatch
User Impact: serious
Guidelines: Experimental
The label-content-name-mismatch
rule ensures that
interactive elements with visible labels have accessible names (such as aria-label
)
that match or include the visible text. This helps screen readers and speech input users interact with controls consistently.
What is being tested?
This rule checks interactive elements (like buttons, links, checkboxes) to ensure:
- The accessible name includes the visible label.
- Attributes like
aria-label
oraria-labelledby
are aligned with the visible text.
Why it matters
Screen reader and speech input users rely on accessible names to interact with elements. If the accessible name does not match the visible label, users may be confused or unable to activate controls using voice commands or assistive technology.
How to fix the problem
- Make sure the
aria-label
or programmatic name includes the visible label text in the same order. - For best practice, start the accessible name with the visible text.
Correct examples
<div role="link" aria-label="Next page">Next page</div> <button aria-label="Next page in list">Next page</button>
Incorrect examples
<div role="link" aria-label="OK">Next</div> <button aria-label="the full">The full label</button>
Best practices
- Ensure the accessible name always includes the visible label.
- For interactive widgets, use native HTML or add appropriate ARIA roles and labels.
- Test with a screen reader or speech input tool to confirm predictable behavior.
Other Rules
Interested in other web accessibility rules? Please see these other rules: