Tooltips

Tooltips Accessibility Skill

Canonical source: examples/TOOLTIP_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when implementing or reviewing tooltip components. Only load this skill if the project contains tooltips.

Core Mandate

A tooltip is a short, non-interactive description that appears automatically when its trigger receives keyboard focus or pointer hover. An accessible tooltip must be available to keyboard, pointer, touch, magnification, and assistive technology users without hiding essential information or blocking the interface.

Tooltips are often the wrong solution. Persistent visible text, a clear control label, a disclosure, or a dialog is usually easier to discover and use. This guide covers authored tooltips; the HTML title attribute produces a browser-controlled tooltip with different behavior and limitations (see below).

Use the project's skills/bug-reporting/SKILL.md severity/priority framework to grade findings. The severity scale below is a skill-local shorthand, not a universal standard.

Severity Scale (this skill)

Choose the Right Pattern First

Calling every small popup a tooltip leads to incorrect semantics and keyboard behavior. Classify the interaction before choosing ARIA:

An authored tooltip: describes an element, appears automatically after focus or hover, contains only non-interactive content, does not receive focus, is associated with its trigger through aria-describedby, remains available while the trigger has focus or the pointer is over the trigger or tooltip, and can be dismissed with Escape.

Critical: Essential Information Must Not Live Only in a Tooltip

A tooltip is supplementary by definition. Put instructions, errors, requirements, and other essential information in persistent visible text. Hiding essential content behind hover/focus only is Critical.

Do not place error messages, legal text, security warnings, or task requirements only in a tooltip. Do not attach essential explanations only to a disabled control — a disabled native form control may not dispatch the pointer/focus events a tooltip expects:

<p id="publish-requirement">Add a page title before publishing.</p>
<button type="button" disabled aria-describedby="publish-requirement">
  Publish
</button>

Serious: Tooltips Must Appear on Both Hover and Focus

A tooltip that only appears on hover is Serious — keyboard users cannot trigger it. Keep focus on the trigger; a tooltip never receives focus. Do not add the tooltip to the tab sequence or use arrow keys to navigate its text.

document.querySelectorAll('[data-tooltip]').forEach((container) => {
  const trigger = container.querySelector('[data-tooltip-trigger]');
  const tooltip = document.getElementById(trigger.dataset.tooltipId);
  if (!tooltip || tooltip.getAttribute('role') !== 'tooltip') return;

  let pointerWithin = false;
  let triggerFocused = false;
  let dismissed = false;

  function updateTooltip() {
    tooltip.hidden = !(!dismissed && (pointerWithin || triggerFocused));
  }

  container.addEventListener('pointerenter', () => { pointerWithin = true; dismissed = false; updateTooltip(); });
  container.addEventListener('pointerleave', () => { pointerWithin = false; updateTooltip(); });
  trigger.addEventListener('focus', () => { triggerFocused = true; dismissed = false; updateTooltip(); });
  trigger.addEventListener('blur',  () => { triggerFocused = false; updateTooltip(); });
  trigger.addEventListener('keydown', (event) => {
    if (event.key === 'Escape' && !tooltip.hidden) {
      dismissed = true;
      updateTooltip();
      event.stopPropagation();
    }
  });
});

Track pointer and focus state separately — closing on pointer-leave when focus still keeps the tooltip active is a common failure. If a positioning library is used, inspect its rendered markup, focus handling, portal location, collision behavior, and cleanup; a library name is not evidence of accessibility.

Serious: ARIA Pattern Must Be Correct

Incorrect ARIA on tooltips is Serious — AT users receive wrong or no supplementary information.

<span class="tooltip-container" data-tooltip>
  <button type="button" aria-describedby="save-tooltip"
          data-tooltip-trigger data-tooltip-id="save-tooltip">
    Save
  </button>
  <span id="save-tooltip" role="tooltip" hidden>
    Saves changes to your draft.
  </span>
</span>

Rules:

• Tooltip element must have role="tooltip"; use a native interactive element for the trigger when the trigger performs an action
• Trigger must reference tooltip via aria-describedby (not aria-labelledby); aria-describedby may hold a space-separated list — preserve existing help, error, or instruction references when adding a tooltip
• Use hidden to conceal; never aria-hidden="true" on an active tooltip
• Each tooltip must have a unique id, including across repeated components; render the descriptive node before focus reaches the trigger
• Do not put role="tooltip" on the trigger itself
• Tooltips must not be focusable — no tabindex on the tooltip container
• Do not add aria-live, role="status", or role="alert" to a tooltip
• Do not use aria-expanded or aria-haspopup for an automatically-displayed tooltip — those apply to button-controlled disclosures, not tooltips
• Let the tooltip's text provide its accessible description; avoid an aria-label that replaces different visible tooltip text

For icon-only triggers, name the control independently — the tooltip is a description, not a replacement for the accessible name:

<span class="tooltip-container" data-tooltip>
  <button type="button"
          aria-label="Delete quarterly report"
          aria-describedby="delete-tooltip"
          data-tooltip-trigger data-tooltip-id="delete-tooltip">
    <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
      <path d="M5 7h14M9 7V4h6v3m-8 0 1 13h8l1-13"/>
    </svg>
  </button>
  <span id="delete-tooltip" role="tooltip" hidden>
    Permanently deletes the report.
  </span>
</span>

Avoid repeating exactly the same words as both name and description.

Serious: Button-Controlled Help Is Not a Tooltip

When a user activates a button to show content, use a disclosure pattern instead — do not give the content role="tooltip" and do not add a live region merely because it became visible:

<button type="button" id="password-help-button"
        aria-expanded="false" aria-controls="password-help">
  Password requirements
</button>
<div id="password-help" hidden>
  Use at least 12 characters. Include a number and a symbol.
</div>

The expanded state communicates the change; focus remains on the button. If the popup contains interactive controls or must manage focus, use an appropriate dialog or popup pattern.

Moderate: WCAG 1.4.13 — Content on Hover or Focus

Do not invent an auto-close duration — a tooltip that disappears after a fixed timeout does not meet the persistence requirement while its trigger remains active.

Moderate: Touch and Activation

Touch devices do not provide dependable hover. Do not depend on a tooltip for touch access. Use one of:

• Keep the information visible near the control
• Include it in the control's accessible name or existing description
• Provide a separate help button that opens a disclosure (see above)
• Use a non-modal dialog when the additional content is structured or interactive

Moderate: Do Not Rely on the title Attribute

Browser-controlled title tooltips fall under the WCAG 1.4.13 exception when their presentation is entirely user-agent controlled, but that exception does not make title a dependable interface pattern. Authors cannot ensure consistent keyboard, touch, magnification, timing, text size, or dismissal behavior for title. Do not use title as the only:

• accessible name for a control
• source of instructions or validation requirements
• explanation of an icon
• way to reveal truncated text
• access path for touch users

Moderate: Visual Design

• Normal-size tooltip text needs at least 4.5:1 contrast against its background (WCAG 1.4.3); large text needs 3:1
• A boundary, shape, or arrow needs 3:1 contrast against adjacent colors (WCAG 1.4.11) only when that visual information is required to identify the component or state — a decorative arrow is not automatically subject to this
• Do not rely on color alone to associate a tooltip with its trigger
• At 400% zoom and narrow viewports: keep the tooltip within the viewport, allow text to wrap, avoid horizontal scrolling, don't cover the trigger or critical content, and preserve a way to dismiss it
• Detect viewport edges and reposition; recalculate placement after zoom, resize, content changes, and text-direction changes; avoid rendering inside an ancestor whose overflow clips the tooltip
• An icon-button trigger must still meet WCAG 2.2 Target Size (Minimum)
• Respect prefers-reduced-motion:

[role="tooltip"] {
  position: absolute;
  max-inline-size: min(20rem, calc(100vw - 2rem));
  overflow-wrap: anywhere;
}
[role="tooltip"][hidden] { display: none; }

@media (forced-colors: active) {
  [role="tooltip"] { color: CanvasText; background: Canvas; border-color: CanvasText; }
}
@media (prefers-reduced-motion: no-preference) {
  [role="tooltip"] { transition: opacity 0.15s ease; }
}

Content Requirements

• Keep content to a short phrase or sentence; describe the trigger, don't introduce an unrelated message
• Avoid repeating the trigger's accessible name word for word
• Do not include headings, lists, links, buttons, fields, or other controls
• Write in plain language; keep dynamic descriptions stable while the trigger has focus
• If content needs structure or several sentences, use persistent help, aria-details, a disclosure, or a dialog instead
• Do not make ordinary prose focusable merely to attach a tooltip — extra tab stops make keyboard navigation harder

When NOT to Use a Tooltip

• Label of control is self-explanatory
• Information must be readable at all times → use persistent help text
• Touch-only interface → use a help button/disclosure or persistent help text
• Content is long or structured → use a popover, disclosure, or dialog
• Content contains interactive elements (links, buttons) → use a popover or dialog

Testing

• Keyboard: reach the trigger with Tab/Shift+Tab, confirm the tooltip appears without moving focus, confirm Escape closes it while focus stays on the trigger, confirm no tooltip tab stop exists, confirm the focus indicator remains visible
• Pointer/magnification: hover the trigger, move the pointer onto every part of the tooltip and confirm it stays visible, confirm it closes when neither hover nor focus retains it, test with screen magnification
• Touch: confirm every action is usable without first discovering hover content; confirm essential information is visible or reachable via an explicit control; test screen reader gestures and confirm long press is not required
• Screen reader: confirm the trigger's accessible name is correct without the tooltip, the tooltip text is exposed as a description, name/description aren't needlessly duplicated, focus is not moved, and repeated focus doesn't produce stale descriptions. Test supported browser/AT combinations and record versions — presentation varies and no single announcement is universal
• Visual/responsive: 200%/400% zoom, narrow viewports, text-spacing overrides, forced-colors mode, reduced motion, RTL text, viewport-edge placement
• Automated: can catch missing/duplicate IDs, unresolved aria-describedby references, invalid ARIA values, focusable descendants inside a tooltip, inadequate contrast, hidden triggers, and stale open tooltips in component tests — but cannot prove hoverability, persistence, positioning, or screen-reader presentation. Keep manual tests in the release process.

Common Failures

Definition of Done Checklist

• A tooltip is the correct pattern (see the pattern-choice table above)
• Essential information is visible without opening the tooltip
• The trigger has a complete accessible name without depending on the tooltip
• role="tooltip" on tooltip element with a unique id
• Trigger references it via aria-describedby without losing other descriptions
• Tooltip appears on both hover and keyboard focus
• Escape dismisses without moving focus; not closed on a fixed timer
• Tooltip hoverable (pointer can move over it without dismissal)
• Tooltip and all descendants are not focusable; no interactive content inside
• Touch users have visible information or an explicit help control
• Disabled controls do not hide their explanation
• Text contrast 4.5:1; required non-text contrast 3:1
• Reflows/wraps and remains operable at zoom and with text-spacing overrides
• prefers-reduced-motion respected for animations
• Tested across keyboard, pointer, touch, magnification, and supported screen readers

Key WCAG Criteria

• 1.3.1 Info and Relationships (A)
• 1.4.3 Contrast Minimum (AA)
• 1.4.10 Reflow (AA)
• 1.4.11 Non-text Contrast (AA)
• 1.4.12 Text Spacing (AA)
• 1.4.13 Content on Hover or Focus (AA) — Serious if hover-only or not dismissible
• 2.1.1 Keyboard (A) — Serious if keyboard cannot trigger tooltip
• 2.1.2 No Keyboard Trap (A)
• 2.4.7 Focus Visible (AA)
• 2.4.11 Focus Not Obscured Minimum (AA)
• 2.5.8 Target Size Minimum (AA)
• 4.1.2 Name, Role, Value (A)

References

• Full best practices guide
• WCAG 2.2 Understanding 1.4.13 Content on Hover or Focus
• WAI-ARIA APG — Tooltip pattern (marked work-in-progress by W3C — useful guidance, not a substitute for user testing)
• Technique SCR39: Hoverable, Dismissible, and Persistent
• Failure F95: Content Shown on Hover Is Not Hoverable

Standards horizon: WCAG 3.0 is in development; 1.4.13 requirements are expected to carry forward. Monitor: https://www.w3.org/TR/wcag-3.0/