SiteLint documentation and guidelines

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 (or button, 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, no aria-label, and no aria-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 carry aria-hidden="true"… but it usually does, leaving the button silent.
  • Broken aria-labelledby references – aria-labelledby points 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 – title on a button provides a name only when no other source exists, and its announcement depends on screen reader settings, so a lone title is 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.

Correct example
<button type="button">Save changes</button>
<button type="button" class="btn-danger">Delete account</button>
<button type="submit">Create account</button>
Incorrect example
<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.

Note that support for the title attribute varies across screen readers. For instance, VoiceOver by default has Hints set to ‘Never’ or ‘Speak after delay’, which may prevent the title from being announced. Do not rely solely on title for critical information.

Correct example
<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>
Incorrect example
<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.

Correct example
<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>
Incorrect example
<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.

Correct example
<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>
Incorrect example
<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.

Correct example
<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>
Incorrect example
<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. -->

Prefer a native HTML button over an element with an ARIA role="button" whenever possible. Native buttons provide built-in semantics, keyboard support, focus behavior, and accessibility. Use ARIA only when a native element cannot meet the requirement.

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 with aria-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

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 4.1.2
  • Rule ID: empty-button-description