axe-core "button-name" buttons must have discernible text in CI

By Kaveh Alemi·Latchkey

axe-core rule button-name found a <button> with no accessible name. WCAG 4.1.2 requires interactive controls to expose a name; an icon-only button needs an aria-label or visually hidden text.

What this error means

axe reports "button-name: Buttons must have discernible text" for a button whose only child is an icon or SVG with no text and no aria-label.

button-name: Buttons must have discernible text (critical)
  Fix any of the following:
    Element does not have inner text that is visible to screen readers
    aria-label attribute does not exist or is empty
    Element's default semantics were not overridden with role="none"
  <button class="icon-btn"><svg>...</svg></button>

Common causes

An icon-only button has no text alternative

The button contains only an SVG or icon font with no aria-label, so screen readers announce nothing meaningful.

The SVG conveys the name but is not exposed

The icon is not marked aria-hidden and carries no <title>, leaving the button with no reliable accessible name.

How to fix it

Give the button an aria-label

1. Add an aria-label describing the action, for example "Delete item".
2. Mark the decorative icon aria-hidden="true" so it is not double-announced.
3. Re-run axe to confirm the button now has a name.

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

Use visually hidden text as an alternative

A visually hidden span provides the name while keeping the button icon-only for sighted users.

<button>
  <svg aria-hidden="true">...</svg>
  <span class="sr-only">Delete item</span>
</button>

How to prevent it

• Require an accessible name on every icon-only control.
• Mark decorative icons aria-hidden to avoid noise.
• Add axe checks for interactive components in the test suite.

Frequently asked questions

Related guides

References

• GitHub Actions documentation