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

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/labels-and-names/label-content-mismatch
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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.

```html
<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.

```html
<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.

```html
<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."

```html
<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.

```html
<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."

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