BUTTON must have an accessible name that describes its action.
Description
This rule automatically scans every <button> HTML element and every element with role="button" and verifies that it exposes an accessible name. The accessible name is the short string that assistive technology announces when the control receives focus, such as Save
or Close
. The rule reports a control when its content is empty, when it contains only whitespace, or when it defines an aria-labelledby reference that points to elements that do not exist in the page. Elements with aria-hidden="true" are deliberately skipped, because their content must not be exposed to assistive technology. This check maps to WCAG Success Criterion 4.1.2 Name, Role, Value (Level A) and to the HTML technique H91: Using button elements.
Every interactive control must announce what it does, not just that it is a button. A button that announces no name forces assistive technology users to guess what will happen when they activate it, which breaks the perceivable and operable promises of the Web Content Accessibility Guidelines. Screen readers produce the accessible name from visible text first, then from aria-labelledby, then aria-label, then other fallbacks. When none of these sources produces text, the control is effectively silent and the audit flags it.
Disabilities impacted
- Screen reader users (blind) – A button with no accessible name is announced only as
button
(orbutton, empty
). The user cannot tell whether activating the control submits a form, opens a menu, or deletes a record, forcing them to inspect surrounding context or risk dangerous actions such as submitting or deleting. - Visual impairments – Users who rely on screen magnification combined with assistive technology tabs through interfaces by reading the focus announcement of each control. An unnamed button produces no useful feedback, making long toolbars or dashboards effectively unpredictable. The rule’s
aria-hidden="true"exception also protects users by ensuring decorative or off-screen controls never leak into the reading order. - Cognitive disabilities – People with memory or comprehension difficulties depend on clear, consistent labels to understand the consequences of an action. An icon-only button that does not announce its purpose adds guesswork and increases errors, especially in destructive operations such as deletion or payment confirmation.
- Motor disabilities – Users who navigate with voice control or switch devices often activate controls by name (for example
click Save
). When a button has no accessible name, voice-control software cannot target it reliably, and the user must fall back on painful coordinate clicking.
Why it matters
Interactive controls must have a computed name, role, and value so that assistive technologies can serialize them to the user. WCAG states this requirement clearly:
The intent of this Success Criterion is to ensure that Assistive Technologies (AT) can gather information about and activate (or set) user interface controls. This includes form inputs, links, and controls generated by scripts. When the name, role, or value of custom controls are represented in a way that Assistive Technologies can access, the user is able to understand the control and how to operate it.
Unnamed buttons are one of the most common accessibility defects in real-world pages, frequently produced by icon fonts, inline SVG sprites, and empty markup left behind by component libraries and CMS editors. Beyond the assistive technology burden, they also affect compliance with the ADA, the European Accessibility Act (EAA), and Section 508 of the Rehabilitation Act, all of which demand that controls be perceivable and operable. Fixing empty buttons is inexpensive, improves machine-readability for browsers and search tools alike, and removes a genuine source of frustration for users who cannot see the rendered interface.
Coding problems and solutions
Common coding problems
- Empty button element –
<button type="button"></button>contains no text, noaria-label, and noaria-labelledby, so the element matches the selector and produces a report. - Whitespace-only content –
<button> </button>or markup with only newlines and spaces looks styled correctly but contributes an empty accessible name. - Icon-only buttons without a name – A button containing only a magnifying-glass or hamburger SVG announces nothing unless the button itself carries
aria-label,aria-labelledby, or meaningful text; the SVG is ignored and must not carryaria-hidden="true"… but it usually does, leaving the button silent. - Broken aria-labelledby references –
aria-labelledbypoints to id values that do not exist in the document, often after a refactor deleted the target element while leaving the reference behind. - Relying on the title attribute alone –
titleon a button provides a name only when no other source exists, and its announcement depends on screen reader settings, so a lonetitleis an unreliable naming strategy. - Unnamed elements with role=”button” – A
<div role="button">or<span role="button">that renders as a button but contains only decorative glyphs gives assistive technology no name to announce.
How to fix it
Give the button visible text content
Prefer real text inside the <button>. Visible text is the first source of the accessible name, is announced by every screen reader, and doubles as the visual label, satisfying both clarity and comprehension.
<button type="button">Save changes</button>
<button type="button" class="btn-danger">Delete account</button>
<button type="submit">Create account</button><button type="button"></button>
<button type="button"> </button>
<button type="submit"><span></span></button>Use aria-label for icon-only buttons
When a button shows only an icon, give it an explicit name with aria-label and hide the decorative icon from assistive technology with aria-hidden="true" plus focusable="false" on the SVG so old browsers do not tab into it. The title attribute works only as a last-resort source of the name and is less reliable than aria-label.
<button type="button" aria-label="Search">
<svg aria-hidden="true" focusable="false" viewBox="0 0 24 24" width="16" height="16">
<path d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 1 0-.7.7l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0A4.5 4.5 0 1 1 14 9.5 4.5 4.5 0 0 1 9.5 14z"></path>
</svg>
</button><button type="button">
<svg viewBox="0 0 24 24">
<path d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 1 0-.7.7l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0A4.5 4.5 0 1 1 14 9.5 4.5 4.5 0 0 1 9.5 14z"></path>
</svg>
</button>
<!-- No aria-label, no text: the button announces nothing.
The SVG is focusable in some browsers and its path text
is meaningless to screen readers. -->Reference existing text with aria-labelledby
When the label for a button already exists elsewhere in the interface, reuse it with aria-labelledby instead of duplicating text. The referenced element contributes its text to the accessible name even when it is visually hidden, as long as it is removed from visual layout rather than with display: none.
<style>
.visually-hidden {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0 0 0 0);
white-space: nowrap;
border: 0;
}
</style>
<button type="button" aria-labelledby="more-label">
<span aria-hidden="true" class="caret-dot"></span>
</button>
<span id="more-label" class="visually-hidden">Show more options</span><button type="button" aria-labelledby="more-lable">
<span aria-hidden="true" class="caret-dot"></span>
</button>
<span id="more-label" class="visually-hidden">Show more options</span>
<!-- Typo: aria-labelledby points to "more-lable",
but the real id is "more-label", so the reference
resolves to nothing and the button has no name. -->Repair aria-labelledby references that point to missing elements
Refactors and template changes frequently delete label elements while leaving the referencing attribute behind. Verify that every id in aria-labelledby exists in the document, and when labels are controlled by JavaScript, keep the referenced element and the button in the same lifecycle so the reference always resolves.
<button type="button" id="cart-btn" aria-labelledby="cart-label">
<span aria-hidden="true">×</span>
</button>
<span id="cart-label" class="visually-hidden">Shopping cart: 2 items</span>
<script>
const cartLabel = document.getElementById('cart-label');
const cartBtn = document.getElementById('cart-btn');
const nameFromState = () => {
cartLabel.textContent = 'Shopping cart: ' + itemCount;
};
cartBtn.addEventListener('click', nameFromState);
</script><button type="button" aria-labelledby="cart-label">
<span aria-hidden="true">×</span>
</button>
<!-- id="cart-label" was removed during a template refactor.
The aria-labelledby reference now resolves to nothing,
and the button is announced as empty. -->Provide an accessible name for elements with role=”button”
When a <div>, <span>, or other element is given role="button", it inherits the naming rules of a button. Text content, aria-label, or aria-labelledby must supply the name, and the element still needs keyboard activation support via tabindex and key handling, because these elements are not natively focusable or activateable.
<div role="button" tabindex="0"
aria-label="Open main menu"
aria-expanded="false"
aria-controls="site-menu">
<span class="menu-glyph" aria-hidden="true"></span>
</div><div role="button" tabindex="0"
aria-expanded="false"
aria-controls="site-menu">
<span class="menu-glyph"></span>
</div>
<!-- No text, no aria-label, no aria-labelledby, and the glyph
is not hidden, so the accessible name computation yields
nothing (or garbage) and the control is unlabeled. -->Known Limitations
- Simplified name computation – The rule uses a simplified accessible name algorithm. Unusual name sources such as complex nested SVG trees, CSS-generated text, or browser-specific AT quirks may produce a name that the audit does not detect, or the reverse. Automated results should be spot-checked with a real screen reader.
- aria-hidden exception – Buttons and
role="button"elements witharia-hidden="true"are deliberately skipped, even when they still contain keyboard focusable descendants. An empty button inside a hidden container is correctly ignored, but the audit will not warn if an unhidden descendant later becomes visible with no name. - Shadow DOM – Buttons rendered inside shadow roots (custom elements, encapsulated component libraries) are not traversed by the rule’s selector, which operates on the light DOM only. Interactive controls inside Web Components must be audited separately.
- Single-page applications (SPAs) and dynamic content – The rule evaluates the DOM at scan time. Buttons that are rendered after an asynchronous request, lazy-loaded on scroll, or mounted after user interaction may not exist yet and will not be reported.
- Frames and iframes – Pages composed with
<iframe>or<frame>embed documents whose buttons are invisible to this rule. Each embedded document must be audited against this criterion independently. - Third-party widgets – Buttons injected by chat widgets, payment iframes, cookie banners, or advertising scripts can be added after the scan completes or inside inaccessible contexts, so they may escape detection and require manual review.
Resources
- WCAG 2.2 Success Criterion 4.1.2 Name, Role, Value – W3C
- Understanding SC 4.1.2 Name, Role, Value – W3C WAI
- Technique H91: Using HTML button elements with links – W3C WAI
- The button element – MDN Web Docs
- ARIA aria-label attribute – MDN Web Docs
- Accessible Name and Description Computation 1.2 – W3C
Rule
- Audit: accessibility
- Standard: WCAG
- Level: A
- Success Criteria: 4.1.2
- Rule ID:
empty-button-description