Visible label must be included in the accessible name
Content available in English only.
Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).
These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.
If the user reads it, they must be able to speak it — visible text must be in the accessible name.
Why this matters and how to fix it
Why this matters
Speech recognition, voice control, and screen reader users expect that the words they see on the screen match what they must speak or navigate to. If the visible label does not match the accessible name, users may be unable to activate controls by voice, causing broken workflows and frustration.
How to fix this issue
Ensure the visible text is included in the accessible name. If additional clarification is needed, append it using `aria-describedby` instead of replacing the visible wording via `aria-label`.
Developer guidance
This issue commonly appears when developers override `aria-label` with longer or different wording for accessibility. The **accessible name must contain the same text the user sees**. For controls with extra clarification, keep the visible label in the accessible name and move extra detail to `aria-describedby` or adjacent instructions.
Code examples
Incorrect Implementation
<button aria-label="Submit form">Send</button>
<!-- Visible label = 'Send'; Accessible name = 'Submit form' → mismatch -->Correct Implementation
<button aria-label="Send">Send</button>
<!-- Visible label and accessible name match → works for screen readers and voice control -->Real-World Examples
Before
<button aria-label="Add item to shopping cart">Add</button>
<!-- Voice command 'Click Add' fails → accessible name does not contain visible label -->After
<button aria-label="Add to cart">Add</button>
<!-- Visible label 'Add' is included → user can say 'Click Add' reliably -->CSS Example (Guidance)
/* If you need to visually adjust label text, style — do not replace it with aria-label */
button span.label { font-weight: 600; }Manual testing
- 1. Identify buttons, links, and form controls with visible text.
- 2. Turn on a screen reader and navigate to each control.
- • Expected: The announced name includes the visible label.
- 3. Use a voice control tool (e.g., Dragon, Voice Control on macOS).
- • Say the visible label, e.g., “Click Send”.
- • Expected: The correct control activates.
- 4. Inspect the accessible name in DevTools → Accessibility → 'Name'.
- • Confirm the accessible name contains the visible text exactly.
- 5. If extra explanation is needed, add it with `aria-describedby` rather than rewriting the main name.
Trusted by organizations across Europe working toward WCAG and EAA conformance