Documentation/Buttons need accessible text

Buttons need accessible text

ZMD011

Every <button> must have a non-empty accessible name from text, aria-label, aria-labelledby, or labeled content.

✅ Good

<button>Submit</button>
<button aria-label="Close"></button>
<span id="close-label">Close</span>
<button aria-labelledby="close-label"></button>
<button><img alt="Close" src="/icon.svg" /></button>

❌ Bad

<button></button>
<button aria-label=""></button>
<button aria-labelledby="missing"></button>
<button><svg></svg></button>

When: A button has an empty accessible name

Warning: <button> missing accessible text

Solution: Provide text, aria-label, aria-labelledby, or labeled content

Why it matters

Accessibility: Unlabeled buttons are announced as ‘button’ only, offering no context to screen-reader users.

SEO: Buttons aren’t indexed by search engines when they lack descriptive names.

In brief

  • Goal: Ensure each button has a non-empty accessible name.
  • What to do: Provide text, aria-label, aria-labelledby, or labeled content (like img alt) for every <button>.
  • Why: Screen readers announce only ‘button’ when no name is provided.

Intent

Prevent unnamed buttons by enforcing reliable accessible-name sources.

Benefits

  • Clear announcements for screen-reader users.
  • Improved keyboard focus and navigation.
  • Early detection of missing names via linters.

Techniques

  • G208: Accessible Name Computation for button content.
  • ARIA6: Using aria-label to provide labels for button elements.

HTML Semantics

The <button> element's label is its accessible name; it can come from text, aria-label, aria-labelledby, or labeled descendants like img alt.

References

Tips & edge cases

  • Prefer visible text when possible; use aria-label or aria-labelledby when the UI is icon-only.
  • If the label lives elsewhere on the page, connect it with aria-labelledby.

See also