Tooltip

Purpose

Tooltips provide supplemental context for interface elements. They appear on hover and focus and disappear when the pointer leaves or focus moves away.

Usage Guidance

• Tooltips should only supplement, not replace, visible labels
• Never put essential or actionable content in a tooltip
• Tooltips must not contain interactive elements (links, buttons)
• Ensure tooltips are not the only source of an element’s accessible name

Accessibility Considerations

• Associate tooltips with their trigger using aria-describedby
• The tooltip element must be in the DOM (not just visually hidden)
• Tooltips must be dismissable with Escape without moving focus (WCAG 2.2 SC 1.4.13)
• Ensure the tooltip does not obscure other content when triggered

Keyboard Support

Screen Reader Behavior

Screen readers read the aria-describedby content after the element’s accessible name. The tooltip text provides supplemental description.

ARIA Requirements

• aria-describedby="tooltip-id" on the trigger element
• The tooltip element has a matching id
• No role="tooltip" is required but may be used for clarity

Common Mistakes

• Putting essential information only in a tooltip
• Tooltips that cannot be dismissed with Escape (WCAG 2.2 violation)
• Tooltips containing interactive elements
• Tooltips that do not appear on keyboard focus (only on hover)

Live Example

Code Example

<button
  type="button"
  aria-describedby="my-tooltip"
>
  VPAT
</button>
<span id="my-tooltip" role="tooltip" hidden>
  Voluntary Product Accessibility Template
</span>

var trigger = document.querySelector('[aria-describedby="my-tooltip"]');
var tooltip = document.getElementById('my-tooltip');

trigger.addEventListener('mouseenter', function() { tooltip.hidden = false; });
trigger.addEventListener('mouseleave', function() { tooltip.hidden = true; });
trigger.addEventListener('focus', function() { tooltip.hidden = false; });
trigger.addEventListener('blur', function() { tooltip.hidden = true; });
trigger.addEventListener('keydown', function(e) {
  if (e.key === 'Escape') tooltip.hidden = true;
});