Accessible tooltips

Shops use tooltips for the "i" icon next to the VAT note, for explaining delivery times, for icon buttons in the header and for size advice. They look simple, but a tooltip that appears only on mouse hover is invisible to keyboard and touch users, and one that covers the content and cannot be closed is a WCAG failure. This page is part of the accessible UI patterns series.

When to use a tooltip

The APG describes a tooltip as "a popup that displays information related to an element when the element receives keyboard focus" or the mouse hovers over it. Use it only for a short, non-essential description of a control — a label for an icon button, a hint. Important information (prices, delivery conditions, return rules) belongs in visible text. Interactive content belongs in a disclosure or a dialog.

Note: the APG says the tooltip pattern is "work in progress; it does not yet have task force consensus." Treat it as a guideline and test with real assistive technology.

Relevant WCAG criteria

• 1.4.13 Content on Hover or Focus (AA). Content that appears on hover or focus must be:

  • dismissible — "a mechanism is available to dismiss the additional content without moving pointer hover or keyboard focus" (usually Escape), unless it communicates an input error;
  • hoverable — the pointer can move over the tooltip without it disappearing;
  • persistent — it stays until the trigger is removed, the user dismisses it or the information is no longer valid.

  The criterion does not cover content whose presentation the browser controls; W3C names the browser tooltip of the title attribute as the main example.

• 2.1.1 Keyboard (A): what appears on hover must also be reachable with the keyboard.

• 4.1.2 Name, Role, Value (A): an icon button needs a name; a tooltip alone is not a reliable name.

• 1.4.3 Contrast (Minimum) (AA): tooltip text needs 4.5:1.

• 2.4.11 Focus Not Obscured (Minimum) (AA): a tooltip must not entirely cover the focused element.

Code example

<!-- Tooltip as description of a focusable control (APG pattern) -->
<button type="button" class="icon-btn" aria-describedby="tip-compare">
  <svg aria-hidden="true" focusable="false"><use href="#icon-compare"></use></svg>
  <span class="visually-hidden">Compare</span>
</button>
<div id="tip-compare" role="tooltip" hidden>Add to comparison list</div>

<!-- Toggletip: information opened by click, not on hover -->
<button type="button" aria-expanded="false" aria-controls="vat-info">
  <span class="visually-hidden">About VAT</span>
  <svg aria-hidden="true" focusable="false"><use href="#icon-info"></use></svg>
</button>
<p id="vat-info" hidden>Prices include VAT for your delivery country.</p>

Script for the tooltip: show it on focus and mouseenter, hide it on blur and on mouseleave of both the trigger and the tooltip (so the pointer can move onto it), and hide it on Escape while focus stays on the trigger. The APG says "tooltip widgets do not receive focus" and "focus stays on the triggering element while the tooltip is displayed". The trigger references the tooltip with aria-describedby.

The second example is a disclosure button, the same APG pattern that accordions are built from: it toggles aria-expanded and the content stays visible until the user closes it — better for touch screens and for longer text.

Keyboard interaction

Common mistakes on online shops

• Hover-only tooltips on "i" icons that are span elements, so keyboard and touch users never see delivery or VAT notes.
• Important conditions only in a tooltip: return deadlines, shipping cost, "price per kilogram".
• The tooltip disappears when the pointer moves towards it, so people using screen magnification cannot read it.
• No Escape, and the tooltip covers the next form field.
• Links inside a tooltip ("Learn more") that can never receive focus.
• Icon buttons named only by title, which is not shown on focus or touch.
• Low-contrast tooltip text, for example light grey on white.

What automated checks catch vs manual testing

All are cards in our rule library. 1.4.13 cannot be tested automatically: the scan sees the page as it loads, not what appears on hover or focus. Test manually: Tab to every trigger, check the tooltip appears, press Escape, move the mouse onto it, zoom to 200% and check it is still readable. The browser extension helps with the rest of the page.

Start with the free one-page check. It is an automated check, not a full audit.

Frequently asked questions

Which WCAG criterion applies to tooltips?

1.4.13 Content on Hover or Focus (level AA). Content that appears on hover or focus must be dismissible without moving the pointer or focus, hoverable so the pointer can move onto it, and persistent until the user removes the trigger or dismisses it.

Is the title attribute an accessible tooltip?

The browser tooltip of the title attribute is outside the scope of 1.4.13, because the browser controls it. It is still a poor way to give important information: it is not shown on keyboard focus or on touch screens.

What is the APG tooltip pattern?

A popup with role="tooltip" that appears when the element receives keyboard focus or the pointer hovers it; the trigger refers to it with aria-describedby, the tooltip never receives focus, and Escape dismisses it. The APG says the pattern is still work in progress without task force consensus.

Can a tooltip contain links or buttons?

No. A tooltip never receives focus, so interactive content inside it cannot be reached. Use a disclosure or a non-modal dialog that opens on click instead.

Can an automated check test tooltips?

It finds role="tooltip" elements without a name and icon buttons without a name. Whether the tooltip appears on focus, stays when hovered and closes with Escape needs a manual test.

Sources

• W3C WAI, APG Tooltip pattern: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
• W3C, Understanding 1.4.13 Content on Hover or Focus: https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html
• W3C WAI, APG Disclosure pattern: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/