Accessibility Required

Put the visible words in the name

When a control shows text, its accessible name must contain that text, ideally at the start. This is WCAG criterion 2.5.3 (A).

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Let the visible text be the name. Add an aria-label only to controls without visible text. If you must add words, keep the visible words first and in the same order, so voice users can say what they see.

Example

<!-- Good: the name starts with the visible words -->
<button type="button" aria-label="Send message to support">Send message</button>
<!-- Bad: someone who says "click Send" cannot reach it -->
<button type="button" aria-label="Submit form">Send</button>

How to check

axe label-content-name-mismatch passes. A test finds no control with visible text whose aria-label leaves that text out.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/accessibility/label-in-name.