How to Fix: "Buttons Do Not Have Accessible Names"

May 26, 2022

The Web Content Accessibility Guidelines (WCAG) require interactive elements to have both a “label" and a “name.” The name (also called the accessible name) is text that software can use to identify a component to a user.

Accessible names are important because many people don’t perceive web content visually. If a person uses a screen reader (software that converts text to audio or braille), the accessible name gives them important context. 

For example, if a button is labeled “click for more information,” the user will know that activating the button will provide them with more information. As long as the accessible name is present, the user can understand its purpose, regardless of what technology they’re using to access the internet. 

However, if components don’t have accessible names, the user must rely on guesswork. The screen reader may announce the name of the component (for example, “button"), but the user won’t receive any useful information about what the button does. 

Related: How Accessible Names Can Help (Or Frustrate) Your Users

Accessible Name Errors in Automated Accessibility Audits

Following an audit, Google Lighthouse and other automated accessibility tools may present an error that reads “Buttons do not have accessible names.” Fortunately, this is usually an easy fix. Below, we’ll outline three solutions. 

Adding Text Content to the Button Element

The simplest way to add accessible names to buttons is to add text content to the button element. This displays the text on the button’s visible label (and if the button doesn’t have a visible label, keep reading). 

Here’s an appropriate use of a text label for a button:

<button>Buy our product</button>

The text should provide the user with clear, concise information about how the element operates. A simple label like “click here" tells the user nothing — they don’t know what “clicking here" will do. A call to action like “buy the product" or “book an appointment" will help people understand the purpose of the button. 

Adding Accessible Names to Buttons with Aria-label

WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) is a specification intended to provide semantic definitions to components when those definitions aren’t natively available in HTML. As we’ve discussed in other articles, ARIA is powerful, and you’ll need to understand how ARIA functions before using it on your website. 

Related: 4 Questions to Ask Before Using ARIA

The ARIA attribute aria-label is useful for adding accessible names to icons and other buttons that do not have visible labels. Once again, your labels should have a clear, concise call to action:

<button aria-label="buy product"> … </button>

Screen readers will announce this as “buy product, button.” Note that the word “button" will appear in the software’s audio output — you don’t include the word “button" in your accessible name.

Adding Accessible Names with Aria-labelledby

Developers can also use the aria-labelledby attribute to provide an accessible name. You’ll want to use aria-labelledby to get the accessible name from another element in the document. 

In other words, if the label already exists somewhere on the page, you can avoid duplicating that label by using aria-labelledby to point to the relevant id attribute.

For examples of how to use aria-labelledby, review this aria-labelledby instruction page from the Mozilla Developer Network.

Quick Tips for Adding Accessible Names to Buttons

Adding accessible names to user interface components can help your website conform with several important WCAG 2.1 Level AA success criteria. Some tips to keep in mind:

  • Understand the priorities of accessible labels. Aria-labelledby always takes preference over aria-label and the element’s inner text.
  • Check third-party plugins and widgets. Third-party content may fail to apply accurate button labels (and if that’s the case, make sure to test thoroughly for other accessibility barriers). 
  • Avoid using ARIA unless it’s absolutely necessary. Semantic HTML is widely supported, so it’s always preferable to ARIA.
  • Don’t use the word “button" in your ARIA markup or in the element’s inner text.

Finally, don’t rely on automated audits alone to check accessible names. Automated tools can detect whether accessible names exist, but they can’t determine whether the names are descriptive and useful. 

To fully conform with WCAG 2.1 — and non-discrimination laws like the Americans with Disabilities Act — we recommend using a combination of manual and automated tests to check your content for accessibility. Visit our Compliance Roadmap for more guidance or contact the Bureau of Internet Accessibility to speak with a subject matter expert.

Receive an industry accessibility analysis of your website

Recent posts

Tips for Meeting WCAG Success Criterion 4.1.1, “Parsing"

December 2, 2022

What Is an ADA Accessible Website? 

December 1, 2022

Providing Too Much Information Can Hurt Web Accessibility

November 30, 2022

Not sure where to start?

Start with a free analysis of your website's accessibility.

GET STARTED