Accessibility Rule: Elements must have their visible text as part of their accessible name

About This Accessibility Rule

When an interactive element displays visible text — like a button saying “Submit” — users naturally expect that text to be the element’s name. However, developers sometimes use aria-label or aria-labelledby to set an accessible name that differs from the visible text. This creates a disconnect: what sighted users see and what assistive technologies announce become two different things.

This is a serious accessibility problem that primarily affects speech input users. These users interact with web pages by speaking the names of controls they see on screen. If someone sees a link labeled “Next Page” and says “click Next Page,” but the accessible name is actually “OK,” the speech command fails. The user has no way to know the correct programmatic name, leading to frustration and an inability to use the interface.

This issue also affects screen reader users and users with cognitive disabilities. When a screen reader announces a name that doesn’t match the visible label, it creates confusion — the user may not be sure they’re focused on the right element. For users with cognitive disabilities who rely on consistent, predictable interfaces, this mismatch adds unnecessary complexity.

This rule checks compliance with WCAG 2.1 Success Criterion 2.5.3: Label in Name (Level A). This criterion requires that when a user interface component has a visible text label, the accessible name must contain that visible text. The intent is to ensure that the words users see on screen can be used to interact with the component, regardless of input method.

The rule applies to elements that meet all three conditions:

The element has a widget role that supports name from content — specifically: button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, searchbox, switch, tab, or treeitem.
The element has visible text content.
The element has an aria-label or aria-labelledby attribute that overrides the default accessible name.

When evaluating the match, leading and trailing whitespace is ignored, and the comparison is case-insensitive. The complete visible text must either match the accessible name exactly or be fully contained within it.

How to Fix

To resolve this issue:

Make the accessible name include the full visible text. If the element’s visible text is “Next Page,” the aria-label must contain “Next Page” — not just part of it, and not something completely different.
Start the accessible name with the visible text. While not strictly required, it’s best practice. This helps speech input users who may only speak the beginning of a label.
Consider removing the aria-label entirely. If the visible text alone is a sufficient accessible name, you may not need an override at all. The simplest fix is often to let the element derive its name from its content naturally.

Examples

Failing: Accessible name doesn’t match visible text

The visible text says “Next” but the accessible name is “OK”:

<div role="link" aria-label="OK">Next</div>

Failing: Accessible name only contains part of the visible text

The visible text is “The full label” but the accessible name is “the full,” which doesn’t include the complete visible text:

<button aria-label="the full">The full label</button>

Passing: Accessible name matches visible text

The aria-label matches the visible text (trailing whitespace and case differences are ignored):

<div role="link" aria-label="Next Page">next page</div>

Passing: Accessible name contains the full visible text

The visible text “Next Page” is fully contained within the accessible name:

<button aria-label="Next Page in the list">Next Page</button>

Passing: No aria-label override needed

When the visible text is already a good accessible name, simply omit the aria-label:

<button>Next Page</button>

Passing: aria-labelledby references text that includes the visible content

<span id="btn-label">Search the full catalog</span>
<button aria-labelledby="btn-label">Search</button>

Here, the visible text “Search” is contained within the accessible name “Search the full catalog,” so the rule passes. The accessible name begins with the visible label, which is ideal for speech input users.

Learn more: