Visible label missing from the accessible name

What label in name means

Voice control users say what they see: “click Search”. The software matches the spoken words against the control’s accessible name, not against the pixels. When the name does not contain the visible words that command fails, with no error explaining why, and the user has to find another way in.

WCAG success criterion 2.5.3 Label in Name, Level A, requires the visible label text to be part of the accessible name. Adding context around it is fine; replacing it is not.

What squirrel checks

One check, label-content-name-mismatch, at severity error. It looks at elements carrying both an aria-label and visible text: button, a, input, select, and anything with role="button" or role="link".

Visible text is gathered by walking the element’s child nodes, skipping any subtree marked aria-hidden="true" or carrying the hidden attribute. Both strings are lowercased and their whitespace collapsed before comparison.

• Fail when the aria-label does not contain the visible text as a substring. Report message: N element(s) where visible text doesn't match accessible name. Items read button: visible="search" vs aria-label="find products", truncating each side at 20 characters, up to ten with a count of the rest. The finding carries the issue Voice control users may not be able to activate these controls.
• Pass with Visible labels match accessible names.
• Info with No elements with aria-label and visible text found.

How to fix it

<button aria-label="Search products">Search</button>

Start the aria-label with the visible words and add the extra context after them. That satisfies both the voice command and the screen reader.

A badge inside the control is the usual false positive. <button aria-label="Notifications">Notifications <span>3</span></button> has visible text “notifications 3”, which the label does not contain. Mark the badge aria-hidden="true", or include the count in the label.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/label-content-name-mismatch"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/label-content-name-mismatch"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/button-name: controls with no accessible name at all.
• a11y/link-text: link names that exist but say nothing useful.
• a11y/aria-labels: where aria-label is the right answer rather than the problem.
• a11y/form-field-multiple-labels: two labels competing to name one control.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• Understanding SC 2.5.3 Label in Name, W3C
• aria-label, MDN
• Accessible name and description computation, W3C

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Each finding shows the visible text and the accessible name side by side. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.