Tooltip

What Is a Tooltip?

A tooltip is a small popup that appears when an element receives focus or hover, providing supplementary description for that element. They are commonly used to explain icon buttons or add hints to input fields.

An important caveat: tooltips are "supplementary," not primary information. Essential information required for an operation should never be placed only in a tooltip.

Why Does Accessibility Matter?

Custom tooltips or relying on the title attribute cause the following problems:

• Not shown to keyboard users. If the tooltip only appears on hover (mouse), users who navigate with Tab won't be able to read the description.
• Not shown to touch users. Smartphones and tablets don't have hover.
• The title attribute is unreliable. It displays slowly, can't be styled, and assistive technology support is inconsistent.
• Can't be dismissed. WCAG requires that supplementary popups can be dismissed with Esc.

The solution is to associate the tooltip with aria-describedby, show it on both focus and hover, and allow dismissal with Esc.

Live Demo (Recommended Implementation)

The button below has an APG-compliant tooltip. Verify that it appears not only on mouse hover but also when focused with Tab, and can be dismissed with Esc.

Keyboard Interaction

Required WAI-ARIA Roles & Properties

Recommended Pattern (Good)

Markup:

<!-- The trigger must be a focusable element (e.g. button) -->
<button type="button"
        id="tip-trigger"
        aria-describedby="tip-text">
  Save
</button>

<!-- The tooltip itself. Not focusable, role="tooltip" -->
<div id="tip-text" role="tooltip" hidden>
  Saves your changes to the server
</div>

Show/hide script (supporting both focus and hover + Esc is the key):

const trigger = document.getElementById('tip-trigger');
const tip = document.getElementById('tip-text');

if (trigger && tip) {
  const show = () => { tip.hidden = false; };
  const hide = () => { tip.hidden = true; };

  // Must show on both focus and hover
  trigger.addEventListener('focus', show);
  trigger.addEventListener('blur', hide);
  trigger.addEventListener('mouseenter', show);
  trigger.addEventListener('mouseleave', hide);

  // Allow dismissing with Esc
  trigger.addEventListener('keydown', (e) => {
    if (e.key === 'Escape') hide();
  });
}

Anti-Pattern (Bad)

The buttons below rely on the title attribute only, or use a hover-only custom tooltip. Focusing with Tab shows no description, and Esc doesn't dismiss anything.

<!-- ❌ Anti-pattern 1: title attribute only -->
<button type="button" title="Saves your changes">Save</button>

<!-- ❌ Anti-pattern 2: hover-only custom tooltip -->
<span class="has-tip">Save
  <span class="tip">Saves your changes</span>
</span>

Implementation Checklist

• The trigger is a focusable element (e.g. <button>)
• The trigger has aria-describedby linking to the tooltip
• The tooltip element has role="tooltip"
• The tooltip appears on both focus and hover
• Esc dismisses the tooltip (focus remains on the trigger)
• The tooltip itself does not receive focus and contains no interactive elements
• Information essential for operation is not placed only in the tooltip

Source (English):Tooltip Pattern — W3C APG(opens in a new tab)