• June 1, 2025

Accessible Button Naming

Rule ID: button-name
Ruleset: axe-core 4.10
User Impact: Critical
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A), WCAG 2.2 (A), Section 508, Trusted Tester, EN 301 549

How to Fix the Problem

To meet accessibility compliance, every <button> element—or any element with role="button"—must have an accessible, discernible name. This ensures that users relying on screen readers can understand the purpose or action of the button.

Use one of the following correct approaches:

1. Text Content:

   html

   KopierenBearbeiten

   <button id="text">Name</button>


   The inner text is read by screen readers.

2. ARIA Label:

   html

   KopierenBearbeiten

   <button id="al" aria-label="Name"></button>


   The aria-label provides an accessible name even if the button has no visible text.

3. ARIA Labelledby:

   html

   KopierenBearbeiten

   <button id="alb" aria-labelledby="labeldiv"></button>
<div id="labeldiv">Button label</div>


   The button references another element that contains the accessible name.

4. Combined Text and ARIA Label:

   html

   KopierenBearbeiten

   <button id="combo" aria-label="Aria Name">Name</button>


   Screen readers will use the ARIA label in favor of the inner text.

5. Title Attribute (use with caution):

   html

   KopierenBearbeiten

   <button id="buttonTitle" title="Title"></button>


   Although not a primary method, the title attribute can serve as a fallback accessible name.

6. If the button is decorative and non-interactive:
   Use:

   html

   KopierenBearbeiten

   <button role="presentation" tabindex="-1"></button>


   This removes it from the accessibility tree and tab order.

Avoid the following incorrect implementations:

• Empty buttons:

  html

  KopierenBearbeiten

  <button id="empty"></button>


• Using only value attribute:

  html

  KopierenBearbeiten

  <button id="val" value="Button Name"></button>


• Empty aria-label:

  html

  KopierenBearbeiten

  <button id="alempty" aria-label=""></button>


• aria-labelledby pointing to a missing or empty element:

  html

  KopierenBearbeiten

  <button id="albmissing" aria-labelledby="nonexistent"></button>
<button id="albempty" aria-labelledby="emptydiv"></button>
<div id="emptydiv"></div>


• Button with a value but no label and tabindex="-1":

  html

  KopierenBearbeiten

  <button id="buttonvalue" value="foo" tabindex="-1"></button>


Why it Matters

Buttons without accessible names are functionally invisible to screen reader users. This means they can’t identify what action the button performs, which significantly hinders navigation and interaction.

Accessible button naming ensures users with visual disabilities can complete key tasks such as submitting forms, navigating modal dialogs, or triggering interactive elements. Without proper labels, the user experience becomes confusing and exclusionary, violating WCAG and other legal accessibility standards.

Rule Description

All <button> elements and any element with role="button" must include a discernible name that describes their function or purpose to users of assistive technologies.

This rule enforces the requirement that buttons must communicate their action clearly through accessible naming strategies like visible text or ARIA attributes.

The Algorithm (in simple terms)

1. Locate every button element on the page.

2. Check whether it has:

   • Visible text content, or

   • A non-empty aria-label, or

   • An aria-labelledby attribute pointing to text content.

3. If none of these exist, the element fails the rule.