ARIA Tooltip Must Have an Accessible Name: How to Fix It

This check flags any element carrying role="tooltip" that has no accessible name of its own. An empty-named tooltip is a container the browser advertises to assistive tech as “tooltip” with nothing inside it to read — so the very hint you built to help ends up announcing pure silence.

A tooltip is a named region, not a bare wrapper

When you apply role="tooltip", you’re telling screen readers “this box holds a supplementary hint.” That promise only pays off if the box exposes text. If the tooltip’s content is injected as an icon, a background image, or gets emptied by a framework before it’s read, the role is left pointing at nothing. Worse, tooltips are often referenced from another control via aria-describedby — if the tooltip has no name, that description resolves to emptiness and the control it’s meant to explain gains nothing.

A real failing pattern and the fix

<!-- FAILING: tooltip role on an empty node, text lives in a pseudo-element -->
<span role="tooltip" class="tip" data-tip="Resets your password"></span>
<!-- .tip::after { content: attr(data-tip); }  <- invisible to AT -->

<!-- FAILING: trigger points at a tooltip that has no readable text -->
<button aria-describedby="tip1">?</button>
<div id="tip1" role="tooltip"><svg></svg></div>

<!-- FIXED: real text inside the tooltip, wired to its trigger -->
<button aria-describedby="tip1" aria-label="Password help">?</button>
<div id="tip1" role="tooltip">Resets your password to a temporary one.</div>

The fix does two jobs: it puts real, selectable text inside the role="tooltip" element (so its accessible name is that text), and it names the trigger button too, since a lone “?” is meaningless on its own. Now hovering or focusing the button both reads the button’s purpose and exposes the hint.

Where tooltip text can go missing

How to detect it on your own site

1. axe DevTools: run a scan and look for “aria-tooltip-name”. It flags every role="tooltip" element whose accessible name computes to empty, with the exact selector.
2. Lighthouse: the Accessibility category reports “ARIA tooltip elements do not have accessible names” when a named tooltip is missing readable content.
3. WAVE: run the extension and check the Details panel for the tooltip role; if no associated text shows, or you see an empty-element alert, the name is missing.
4. Manual inspector check: select the tooltip node in the browser Accessibility pane and read its computed “Name.” Blank means it fails — and anything the trigger’s aria-describedby points to will resolve empty too.

How to fix it

1. Put the hint as real text directly inside the role="tooltip" element. Not a pseudo-element, not a background image, not a bare data- attribute — actual text the DOM contains.
2. Ensure the tooltip content exists in the DOM when assistive tech reads it. If your library injects text only on hover, confirm it’s also present on keyboard focus and stays long enough to be announced.
3. Wire the tooltip to its trigger with aria-describedby pointing at the tooltip’s id, so the hint is announced as a description of the control.
4. Give the trigger its own accessible name too — an icon-only “?” button needs aria-label so it isn’t announced as just “button.”
5. Re-scan; aria-tooltip-name should return zero violations.

Why an empty tooltip is worse than none

Skip the tooltip entirely and a screen-reader user simply doesn’t get the hint — no harm, just no help. Ship a named-but-empty tooltip and you actively mislead: assistive tech announces “tooltip,” the user expects information, and gets dead air. On complex forms where tooltips explain password rules, tax fields, or shipping caveats, that silence is the difference between finishing the form and bailing on it. And because tooltips are frequently the payload of an aria-describedby relationship, an empty one quietly guts the description of the control it was supposed to support. The same naming discipline governs ARIA toggle fields and other unnamed widgets.

FAQ

Can I use the title attribute instead of role="tooltip"?

For a plain text hint, native title is often simpler and needs no ARIA — but it’s invisible on touch devices and unreliable for keyboard users. If you build a real tooltip widget, use role="tooltip" with genuine text and wire it up properly.

Does the tooltip need to be focusable?

The tooltip itself usually shouldn’t be a tab stop — the trigger is. The tooltip appears on the trigger’s hover/focus and is announced via aria-describedby. Making the tooltip a focus target on its own tends to trap keyboard users.

Why doesn’t my CSS-generated tooltip text count?

Content produced by ::before/::after or by rendering a data- attribute lives in the render tree, not the DOM, so the accessibility-name algorithm can’t see it. Only real DOM text (or an ARIA name) is exposed.

Is role="tooltip" even required?

Not always. Many robust tooltips work with just aria-describedby pointing at a plain <div> of text. But once you’ve declared role="tooltip", this check holds you to giving it a name.

What about tooltips that show on click, not hover?

Same rule — the trigger controls visibility, the tooltip holds real text, and aria-describedby (or aria-labelledby if it names rather than describes) exposes it. Click-triggered hints should also be dismissible with Escape. Pair this with a correct base role for the trigger element.