Interactive elements with visible text must have accessible names that contain that text.

When an interactive element like a button or link has visible text, its accessible name must contain that visible text. The accessible name is what assistive technologies announce and what voice control software uses to identify controls. If the accessible name (set through aria-label or aria-labelledby) does not include the visible text, a disconnect occurs between what users see on screen and what assistive technologies report.

This mismatch causes real problems for people who use voice control software, such as Dragon NaturallySpeaking. These users activate controls by speaking the text they see. If a button displays "Send" but has aria-label="Submit form", a voice control user who says "click Send" will get no response, because the accessible name does not contain the word "Send." The user has no way to know what the actual accessible name is without trial and error. Screen reader users also experience confusion when the announced name does not match what sighted colleagues or documentation refer to on screen.

This rule maps to WCAG 2.5.3: Label in Name (Level A). The success criterion requires that when a user interface component has a visible text label, the accessible name includes that visible text. This is a Level A requirement, meaning it is a baseline expectation for all conforming web content starting from WCAG 2.1.

Which elements are affected

This rule applies to elements with a widget role that supports name from content, where the element has visible text and an aria-label or aria-labelledby attribute. The affected roles include button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, searchbox, switch, tab, and treeitem.

If an element does not have aria-label or aria-labelledby, its accessible name typically comes from its text content directly, so there is no mismatch to worry about.

How to fix it

The fix depends on the situation, but the principle is straightforward: make the accessible name contain the visible text.

• If the aria-label does not need to differ from the visible text, remove it entirely and let the accessible name derive from the element's content.
• If you need a more descriptive accessible name, make sure the visible text appears within it. For example, if a button shows "Send," an acceptable aria-label would be "Send message" because it contains the word "Send."
• If you are using aria-labelledby, make sure the referenced elements include the visible text of the control.
• Matching is case insensitive, and leading or trailing whitespace is ignored.

Examples

Incorrect: accessible name does not contain visible text

This button displays "Send" but has an aria-label of "Submit form." A voice control user saying "click Send" cannot activate it.

<button aria-label="Submit form">Send</button>

Incorrect: accessible name partially matches but omits visible words

The link displays "ACT rules" but the aria-label is "ACT guidelines." The word "rules" is missing from the accessible name.

<a href="https://act-rules.github.io/" aria-label="ACT guidelines">ACT rules</a>

Correct: accessible name matches visible text exactly

The aria-label matches the visible text, so there is no mismatch.

<button aria-label="Send">Send</button>

Correct: accessible name contains visible text with additional context

The button displays "Send" and the aria-label is "Send message." Because the visible text "Send" appears within the accessible name, voice control users can still activate it by saying "click Send."

<button aria-label="Send message">Send</button>

Correct: no aria-label, so accessible name comes from content

Without an aria-label or aria-labelledby, the accessible name is derived from the element's text content. There is no opportunity for mismatch.

<a href="https://act-rules.github.io/">ACT rules</a>

Correct: aria-labelledby includes the visible text

The aria-labelledby attribute references an element whose text contains the visible label text. The button displays "Delete" and the accessible name becomes "Delete item 3," which contains "Delete."

<span id="action">Delete item 3</span>
<button aria-labelledby="action">Delete</button>

Learn more:

W3C Reference

Understanding Success Criterion 2.5.3: Label in Name

→

W3C Reference

Technique G208: Including the text of the visible label as part of the accessible name

→