Features

Ensure that elements labelled through their content must have their visible text as part of their accessible name

Rule ID: label-content-name-mismatch User Impact: serious Guidelines: Experimental

The label-content-name-mismatch rule ensures that interactive elements with visible labels have accessible names (such as aria-label) that match or include the visible text. This helps screen readers and speech input users interact with controls consistently.

What is being tested?

This rule checks interactive elements (like buttons, links, checkboxes) to ensure:

  • The accessible name includes the visible label.
  • Attributes like aria-label or aria-labelledby are aligned with the visible text.

Why it matters

Screen reader and speech input users rely on accessible names to interact with elements. If the accessible name does not match the visible label, users may be confused or unable to activate controls using voice commands or assistive technology.

How to fix the problem

  • Make sure the aria-label or programmatic name includes the visible label text in the same order.
  • For best practice, start the accessible name with the visible text.

Correct examples

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

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

Incorrect examples

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

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

Best practices

  • Ensure the accessible name always includes the visible label.
  • For interactive widgets, use native HTML or add appropriate ARIA roles and labels.
  • Test with a screen reader or speech input tool to confirm predictable behavior.

Other Rules

Interested in other web accessibility rules? Please see these other rules: