Why do buttons and links need accessible names?

interactive-element-missing-name page

The issue

A button or link without an accessible name can’t be used by anyone who doesn’t see it. A screen reader announces “button” or “link” and nothing more, a keyboard user tabs to a control with no description, and someone using voice control has no name to say. The control works with a mouse, so it passes every visual check.

The cause is that the browser’s accessible name computation came back empty. It looks, in order, at aria-labelledby, aria-label, the element’s text content, and finally its title, and none of them held any text. WCAG 4.1.2 (Name, Role, Value), a Level A criterion, requires every control to have a name.

Typical sources are a <button> holding only an <svg> or an icon font with no text, an <a> wrapping an <img> with no alt, an empty <a href> laid over a card, and text hidden with display: none or visibility: hidden, which removes it from the name as well.

Scope

Each <button>, each <a> with an href, and each element with a button or link role is checked on its own. Controls in shared headers, navigation and footers repeat on every page that includes them, so fixing the shared component fixes every page.

How to check you have it

• In probeo: the page reports button-name, “Buttons must have discernible text”, or link-name, “Links must have discernible text”. Related rules cover input-button-name and aria-command-name for elements given a command role.
• By hand: inspect each icon-only button and image link, and confirm it has text, an aria-label, an aria-labelledby, or an image with alt.
• With a tool: the accessibility pane in Chrome or Firefox DevTools shows each element’s computed name. An empty name is the failure.

FAQ

How do I label an icon-only button?

Add aria-label to the button element with a description of the action, not the icon. A magnifying glass button is labeled ‘Search’, not ‘Magnifying glass’. Alternatively, include a visually hidden <span> with the label text inside the button. Both approaches produce a computed accessible name without changing the visual design.

Does the title attribute work as a fallback?

Technically yes — it is the last source in the name computation. In practice, title is unreliable. Screen readers do not consistently announce it. It is invisible to touch device users. It creates a tooltip that may obscure content. Use aria-label or text content instead. Reserve title for supplementary information, not as the primary name source.

How should SVG links be labeled?

If an <a> wraps an SVG with no text, add an aria-label to the link. Under the accessible name specification, an SVG with role="img" and its own aria-label also gives the link its name, but a name on the link itself is simpler and easier to check.

What is the difference between aria-label and aria-labelledby?

aria-label is a string value on the element itself. aria-labelledby references one or more other elements by ID and uses their text content as the label. aria-labelledby takes precedence in the name computation. Use aria-labelledby when a visible label already exists elsewhere on the page. Use aria-label when the label needs to exist only in the accessibility tree.

Can CSS-hidden text provide an accessible name?

Only if the hiding technique keeps the text in the accessibility tree. The common ‘sr-only’ or ‘visually-hidden’ class pattern (position: absolute, width: 1px, height: 1px, overflow: hidden, clip) works correctly. display:none and visibility:hidden remove the text from the accessibility tree entirely. Those styles make the text invisible to both sighted users and screen readers.

Do placeholder attributes count as accessible names for buttons?

No. Placeholder is defined for input elements, not buttons or links. Even on inputs, placeholder does not reliably serve as an accessible name. It disappears when the user types, and some assistive technology does not treat it as a label. Use a <label> element for inputs and aria-label or text content for buttons and links.