ARIA Button, Link, and Menuitem Must Have an Accessible Name: How to Fix It

What this issue means

Some controls on your page are not real buttons or links. A developer took a generic element such as a <div> or <span> and added an ARIA role to make it behave like a command. The three command roles are button, link, and menuitem. Assigning one of these roles promises assistive technology that the element is interactive. That promise is incomplete unless the control also carries an accessible name: a short piece of text that tells the user what it does.

This check flags every element with one of those roles that has no discernible name. Common culprits are icon-only buttons (a gear, a magnifying glass, a hamburger menu), image-based links with no alternative text, and custom menu widgets built from plain markup.

Why it matters

A sighted visitor sees the gear icon and understands it opens settings. A screen reader user hears only "button" with no further description. They cannot tell a Search button from a Delete button from a Close button, so they often skip the control or activate it by accident.

This is a documented failure of WCAG Success Criterion 4.1.2 Name, Role, Value, a Level A requirement: every user interface component must expose a programmatically determinable name and role. An accessible name is also the label voice-control users speak to activate a control, and the label machine readers and AI agents rely on to interpret your interface, which is why explicit names are part of building a machine-readable web.

How it gets flagged

Automated tools detect this without rendering the icon. The Deque axe engine reports it under the rule id aria-command-name, which checks every role="button", role="link", and role="menuitem" element for a non-empty accessible name. Google Lighthouse surfaces the same check in its Accessibility category. A control passes with any one of: inner text exposed to assistive technology, a non-empty aria-label, an aria-labelledby pointing to text, or a title attribute.

How to fix it

Option 1: Use a native element (preferred)

The cleanest fix is to stop reinventing controls. A native <button> or <a href> brings the correct role, keyboard behavior, and focus handling for free. You only need to supply the name.

<!-- Native button with visible text -->
<button type="button">Search</button>

<!-- Icon-only native button, name via aria-label -->
<button type="button" aria-label="Search">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

Option 2: Add a name to the ARIA control

If you must keep the ARIA role, give it a name with one of the methods below.

<!-- Visible inner text -->
<div role="button" tabindex="0">Submit</div>

<!-- aria-label for an icon-only control -->
<div role="button" tabindex="0" aria-label="Close dialog">
  <span aria-hidden="true">&times;</span>
</div>

<!-- aria-labelledby pointing to existing text -->
<span id="lbl">Open settings</span>
<div role="button" tabindex="0" aria-labelledby="lbl">
  <svg aria-hidden="true">...</svg>
</div>

Keep names short and specific. Write what the control does ("Close dialog"), not what it looks like ("X icon"). Hide decorative icons with aria-hidden="true" so they do not interfere with the name. For deeper guidance see our checks on buttons must have discernible text and links must have discernible text.

False positives and edge cases

A few patterns can trip the rule even when the intent looks fine:

• Name injected after load. If JavaScript sets the label only after a delay, a snapshot scan may catch the control before the name exists. Re-test after the interface settles, and prefer markup named on first render.
• Text hidden the wrong way. Inner text styled with display:none or visibility:hidden is removed from the accessibility tree, so it does not count. Use a visually hidden (clip) technique for a label that is read but not seen.
• aria-labelledby that points nowhere. If the referenced id does not exist or its target is empty, the name resolves to nothing. Confirm the id matches real text.
• Wrong role on a non-control. If an element was never meant to be interactive, the fix is to remove the role, not bolt on a label.

Frequently asked questions