Tooltips: Naming vs. Describing

Tooltips are small text overlays used to explain UI controls. They're most commonly seen on icon-only buttons, where hovering reveals a short hint. While the pattern seems straightforward, the accessibility community has converged on a narrow definition that shapes how tooltips should be built.

Two properties define a true tooltip: it is a popover, and it must not contain interactive content. If you find yourself wanting to add a button or any other interactive element inside it, then what you actually need is a dialog. The reasoning is simple: a aria-haspopup attribute signals interactive content, which is incompatible with the purely informational tooltip role.

Two Types, Two ARIA Strategies

Broadly, tooltips serve one of two purposes: labeling an icon or providing a contextual description. The correct ARIA approach depends entirely on which of these you're implementing.

Primary Labels for Icon-Only Controls

When a tooltip is the only way to identify an icon button — where the icon has no adjacent visible text — it functions as the button's accessible name. In this case, you should attach the tooltip using aria-labelledby. This is valid as long as the tooltip content is a concise, one- or two-word label.

The attribute also accepts multiple id references. This lets you combine a label with contextual data; for instance, a notifications bell might be labeled by both "Notifications" and a separate element containing the current count, like "3." The accessibility tree will concatenate the referenced text.

Auxiliary Context Through Description

If the tooltip conveys extra description rather than serving as the name, you must pair it with aria-describedby. Applying this attribute alone yields an inaccessible result: screen readers need an accessible name for the control itself.

A practical technique is to include the primary label as the button's text content, but hide it visually (using a standard visually hidden CSS utility). Then, apply aria-describedby to link the auxiliary details. A screen reader user then gets the full picture: first the button's name, then the descriptive text from the tooltip.

Rules of Engagement

Beyond attaching semantics, how a tooltip appears and disappears contributes to a smooth experience.

Open tooltips on mouseover and focus, and dismiss them on mouseout and blur. One important nuance: a mouse user should be able to move their pointer onto the tooltip content without it disappearing. And when the tooltip is open, a keyboard user can close it by pressing Escape — this is a requirement of WCAG 2.2 Success Criterion 1.4.13.

Among the recurring pieces of advice:

  • Do use the tooltip role. Though today's screen readers largely ignore it, adding it may improve compatibility with emerging assistive software.
  • Don't rely on the HTML title attribute; it has a long list of documented accessibility drawbacks.
  • Don't put mission-critical information inside a tooltip. While rare, some assistive technologies may fail to announce the contents of aria-labelledby or aria-describedby elements.

When to Avoid the Pattern

Tooltips belong to pointer and keyboard paradigms; they collapse entirely on touch interfaces, because a user can neither hover over a button nor move focus to it. The most accessible design choice is often to opt out: if you can permanently include the label or descriptive phrase in your visual layout, do that instead.

If the interaction requires more room or interactive content, there are adjacent patterns with better support networks. The HTML <dialog> element is an explicit recommendation. Another, simpler cousin is a "toggletip" — an information balloon that is permanently exposed or toggled active by a button, typically depicted by a small "i" icon. Toggletips exist to reveal information only, and serve those informational icons inside a wrapping <button> element. The content becomes available to screen readers via an assertion in a live region, allowing the information to be conveyed when it is shown to sighted users.