Accessible Tooltips

Build keyboard and screen-reader accessible tooltips using aria-describedby and role="tooltip".

Overview

Tooltips provide supplementary information about a UI element, typically shown on hover. The native title attribute provides a basic tooltip but it has significant accessibility issues: it's invisible to keyboard users, has no hover delay control, and can't be styled. A proper accessible tooltip uses: - role="tooltip" on the tooltip element - aria-describedby on the trigger element pointing to the tooltip's id - Visibility toggled on mouseover/focus for keyboard accessibility - Escape key closes the tooltip Don't put essential information only in tooltips they are supplementary, not primary.

Key Points

•role="tooltip" marks the element as a tooltip for screen readers
•aria-describedby on the trigger links it to the tooltip for screen reader description
•Show tooltip on both hover AND keyboard focus (not hover only)
•Escape key should close the tooltip when it is visible
•Don't put critical information only in tooltips it's inaccessible to touch users
•The title attribute alone is insufficient keyboard and touch users can't see it

Examples

Accessible tooltip with aria-describedby

<style>
  .tooltip-container { position: relative; display: inline-block; }
  [role="tooltip"] {
    position: absolute;
    bottom: calc(100% + 8px);
    left: 50%;
    transform: translateX(-50%);
    background: #111;
    color: white;
    padding: 4px 8px;
    border-radius: 4px;
    font-size: 0.875rem;
    white-space: nowrap;
    pointer-events: none;
    display: none;
  }
  .tooltip-container:hover [role="tooltip"],
  .tooltip-container:focus-within [role="tooltip"] {
    display: block;
  }
</style>

<span class="tooltip-container">
  <button
    type="button"
    aria-describedby="copy-tooltip"
    id="copy-btn"
  >Copy</button>
  <span
    id="copy-tooltip"
    role="tooltip"
  >Copy to clipboard</span>
</span>

focus-within shows tooltip when the button is focused works for keyboard users.

Icon button with tooltip for the label

<span class="tooltip-container">
  <button
    type="button"
    aria-describedby="delete-tip"
    aria-label="Delete item"
  >
    <svg aria-hidden="true" focusable="false" width="20" height="20" viewBox="0 0 24 24">
      <path d="M3 6h18M8 6V4h8v2M19 6l-1 14H6L5 6" stroke="currentColor" stroke-width="2" fill="none"/>
    </svg>
  </button>
  <span id="delete-tip" role="tooltip">Delete this item permanently</span>
</span>

aria-label provides the accessible name; aria-describedby provides the tooltip description.

Common Mistakes

Only showing tooltip on hover keyboard users who Tab to the button never see it
Putting essential information (like required format) only in a tooltip use visible helper text instead
Using the title attribute as the only tooltip invisible to keyboard and touch users

Note

The distinction between aria-label and aria-describedby: aria-label replaces the element's accessible name; aria-describedby adds supplementary description. For an icon button, aria-label is the primary label; aria-describedby points to the tooltip for extra context.

Accessible Tooltips

Overview

Key Points

Examples

Common Mistakes

Note

Exercises

Knowledge Check

What is the difference between aria-label and aria-describedby on a button?