Tooltip
How the Tooltip works with a keyboard and assistive tech, and where it stands against WCAG 2.2 AA.
A tooltip is a short description that appears when its trigger is hovered or focused. It follows the WAI-ARIA tooltip pattern: role="tooltip" on the bubble, aria-describedby on the trigger, opened by keyboard focus as well as the pointer, and closed with Escape. The trigger keeps focus throughout.
Keyboard#
Focusing the trigger shows the tooltip at once, without the hover delay.
Moving focus away hides it.
Hides the tooltip. Focus stays on the trigger.
Semantics#
role="tooltip"Marks the bubble as a description of another element.
Alwaysaria-describedbySet on the trigger only while the tooltip shows, pointing at the bubble's id.
While openaria-labelA tooltip describes; it does not name. An icon-only trigger still needs its own aria-label, with the same words.
Icon-only triggeraria-hiddenThe tail and the globe icon are decorative.
Tail and icon<button aria-label>The Large card's close button. It cannot be reached by keyboard inside a tooltip, so do not rely on it: see the checklist.
dismissibleColour contrast#
Every variant and state has to meet WCAG 2.2 Level AA. Measure the colours as they land on screen: a translucent hover or press wash over whatever sits behind it.
Label and description · Light, Dark
12 to 16px text against the bubble. Light puts #2a2a2a and #6d6d6d on white; Dark puts white and 70% #cbcbcb on #070707.
WCAG 1.4.3 Contrast (Minimum) ↗Icon · Large
The Large card's icon is #8f8f8f on white (3.23:1) and #6d6d6d on dark (3.89:1). It is decorative, so it only needs 3:1 if it carries meaning.
WCAG 1.4.11 Non-text Contrast ↗Bubble edge · Light
The #f2f2f2 stroke measures 1.12:1 on a white page. The text, not the edge, is the content.
WCAG 1.4.11 Non-text Contrast ↗Hover and focus content · Every tooltip
Escape hides it without moving the pointer or focus; the pointer can move onto the bubble, with a 120ms grace, without it closing; and it stays until the trigger loses hover or focus.
WCAG 1.4.13 Content on Hover or Focus ↗Measured contrast#
Label (or Large title) and description text against the bubble, in both themes. All 4 pairs reach their minimum.
Motion#
- On hover the tooltip waits 150ms, so it does not flash as the pointer passes. On keyboard focus it shows at once.
- It fades in over 140ms only when motion is allowed; under prefers-reduced-motion it appears without the fade.
Checklist#
Never put the only copy of something people need in a tooltip. Touch screens only see it on focus, not on tap.
The trigger is one focusable element, such as a button. A tooltip on a <span> or a disabled button cannot be reached by keyboard.
Keep the text to a short phrase. Anything with links, buttons or more than a sentence belongs in a Popover.
The Large card's close button is not keyboard reachable: tabbing to it blurs the trigger and closes the tooltip. Use a Popover when people need to dismiss something.
The bubble flips or shifts to stay in the window, so it is never clipped at a screen edge.