← All rules

Names and roles

Buttons need a name

• Rule: button-name
• Severity: Critical
• WCAG level A

Why it matters

A button whose only content is an icon is announced as "button" and nothing more. In a toolbar of six icons, all six sound the same.

How to fix it

1. Put visible text in the button where the design allows it.
2. Otherwise add aria-label with the action, phrased as a verb ("Close dialog").
3. Set aria-hidden="true" on the icon so it is not read alongside the label.
4. Check that a CSS-hidden label is not the only name — display:none removes it from the name too.

In markup

<button><svg aria-hidden="true">...</svg></button>

<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>

The requirement behind it

This rule is one way of failing the following WCAG 2.2 success criteria. The W3C, which writes the standard, explains each of them:

• 4.1.2 Name, Role, Value (opens in new tab) — WCAG level A

Further reading

Deque University on button-name (opens in new tab)

Deque maintains axe-core, the open-source engine our scanner runs. Their page documents the rule as the engine implements it.

Automated checks find failures a browser can prove. They cannot judge whether a caption is accurate, whether an alt text is useful, or whether a page can be operated end to end with a keyboard — those need a person.