"Buttons must have discernible text": how to fix buttons with no name
Published · Updated
“Buttons must have discernible text” is the error you’ll see in axe. Lighthouse calls it “Buttons do not have an accessible name”, WAVE calls it “Empty button”, and the Tabwise scan calls it “Buttons with no readable name”. They all mean the same thing.
Some buttons on a website are just icons: three lines for the menu, a magnifying glass for search, a bag for the basket. If those buttons have no hidden name, a screen reader just says “button”. The person using it has no idea what it does.
This blocks sales. In our study of Irish online shops, one in six (16% of 2,385) had at least one button with no name. If someone can’t find “Add to basket”, they can’t buy from you.
Who this affects
Mainly people who use a screen reader. That’s software that reads the page aloud, used by blind people and many people with low vision. It reads out each button’s name as they move through the page.
It also affects people who use voice control. They press a button by saying its name, like “click Search”. If the button has no name, there’s nothing to say.
For online shops there’s a legal side too. In Ireland, the Competition and Consumer Protection Commission (CCPC) is the body that checks online shops against the accessibility rules. Our explainer on which accessibility standard applies covers the rules themselves.
What “buttons must have discernible text” means
If you’ve run an accessibility checker, you may have seen this message: “Buttons must have discernible text”. It sounds technical, but it just means some buttons have no name that a screen reader can read out.
The button looks fine. It works fine with a mouse or a finger. But under the hood, there’s nothing telling assistive technology what it’s for.
Why it happens on so many sites
These are the buttons we see most often with no name:
- the menu button (three lines) on mobile
- the search button (a magnifying glass)
- the basket or cart button
- the plus and minus buttons for quantity
- the arrows on slideshows and product carousels
- the X that closes a pop-up or chat window
Almost all of these come from your theme, an app or a plugin. It’s very rarely something you typed in yourself.
Icon links, like social media logos, have the same problem. Our guide to links that say nothing covers those.
That’s why the problem is more common on shops. In our study of Irish Shopify stores, it was 15% of 1,004. Across all Irish business websites we tested it was 14% of 6,576. Among local services, which have fewer shop buttons, it was just 6% of 5,794.
How to fix it
Because this is usually a theme or app problem, the fix is often an email to the right people. Your job is to find out which button is affected and who made it.
Run our free scan first. The report tells you which buttons have no name.
Shopify
If it’s a button in your theme, like the menu, search or basket, contact your theme’s developer.
If it’s a button from an app, like a reviews widget, a chat bubble or a pop-up, contact that app’s developer. You’ll find them on the app’s listing in the Shopify App Store.
WordPress and WooCommerce
Theme buttons are for your theme’s developer. Buttons in sliders, pop-ups, chat widgets or booking forms usually come from a plugin, so contact the plugin’s developer.
Using a page builder? Look in the icon button’s settings for a field called label, title or accessible name. Fill it in, then run our free scan again to check it worked.
Wix
Wix’s Accessibility Wizard can scan your site and list problems for you. If it flags a button you can’t find a setting for, such as the mobile menu or the cart, contact Wix support.
For buttons you added yourself, check the button’s settings for a text or accessibility field. Fill it in, then run our free scan again to check it worked.
Squarespace
If our scan flags the menu, cart or search button and there’s no setting for it, contact Squarespace support. Tell them which button. For buttons added by third-party code, contact whoever supplied the code.
If someone else built your site
Copy this and send it to your web person:
Some buttons on our website have no accessible name, which fails WCAG 2.1 AA (success criterion 4.1.2). Please give every icon button a name that says what it does, including the mobile menu, search, basket, quantity, slideshow and close buttons. If they come from a theme or app, can you tell me which one?
How to check it’s fixed
Run our free scan again. It lists any buttons that still have no name. It checks your homepage and up to four pages linked from it, so look at your other product and checkout pages too.
For other pages, try the free WAVE checker from WebAIM. Type in the address of any page and look for “Empty button” in the results. Chrome also has a free checker built in, called Lighthouse. Run its accessibility check and look for “Buttons do not have an accessible name”.
You can also try a simple test. Press the Tab key to move from button to button. Can you reach every one, including the basket and the quantity buttons? If you can’t reach a button with the keyboard, that’s a separate problem worth reporting too.
For your web developer
The rule is WCAG 2.1 success criterion 4.1.2, Name, Role, Value. axe reports it as button-name.
- Every
<button>needs an accessible name. Visible text is best. For icon-only buttons, usearia-labelor visually hidden text, and hide the icon:
<!-- Before -->
<button class="menu-toggle">
<svg>…</svg>
</button>
<!-- After -->
<button class="menu-toggle" aria-label="Menu" aria-expanded="false">
<svg aria-hidden="true" focusable="false">…</svg>
</button>
- Name quantity buttons with the product: “Decrease quantity for Wool scarf”, not just “minus”.
- Close buttons need a name like “Close” or “Close chat”.
- Use a real
<button>for actions, not a<div>or<a href="#">. A div with a click handler can’t be reached by keyboard. - Check buttons injected by apps and widgets, which often load after the page and aren’t in the theme code.