Tooltip

A tooltip is a small popup providing brief contextual information when a user hovers over or focuses on a trigger element, and it must be dismissable with the Escape key.

Demo

Hover your pointer over the trigger element to reveal the tooltip. Then tab to the trigger with the keyboard to confirm the tooltip also appears on focus. While the tooltip is visible, press Escape to dismiss it. Notice that the tooltip content is read by a screen reader when the trigger receives focus.

What to Observe

• The tooltip appears on both hover and keyboard focus — not only on hover, which would make it inaccessible to keyboard users.
• Pressing Escape while the tooltip is visible dismisses it and returns focus to the trigger without disrupting the user's place in the page.
• A screen reader announces the tooltip content when focus lands on the trigger, without requiring the user to navigate to the tooltip separately.
• The tooltip content is purely informational — it contains no links, buttons, or other interactive elements.
• The tooltip does not disappear automatically after a short timer; it remains visible as long as the trigger is hovered or focused.

Anatomy

[Anatomy image placeholder — will be added when assets are available]

1. Trigger element: The focusable element (button, icon, or link) that a user hovers over or focuses on to reveal the tooltip; it carries an aria-describedby attribute pointing to the tooltip content.
2. Tooltip container: The popup element with role="tooltip" and a matching id referenced by the trigger's aria-describedby.
3. Tooltip text: The brief descriptive message inside the container; it supplements context but does not replace the trigger's own accessible name.
4. Caret or pointer: An optional visual arrow connecting the tooltip bubble to its trigger, helping users understand which element the tooltip describes.

Accessibility Behavior

• The tooltip must appear on both pointer hover and keyboard focus — hover-only tooltips are inaccessible to keyboard users.
• The tooltip element must have role="tooltip", and the trigger must reference it through aria-describedby so screen readers read the content as supplemental description.
• Pressing Escape while the tooltip is visible must dismiss it without moving focus away from the trigger.
• The tooltip must not contain interactive elements such as links or buttons — it is a read-only description, not a dialog.
• The tooltip must remain visible long enough for users to read it — it must not auto-dismiss after a brief timeout.
• Tooltip text must supplement the trigger's label and never serve as the trigger's only accessible name.

Common Mistakes

• Triggering the tooltip only on hover, making it completely unreachable for keyboard users and touch device users.
• Placing interactive content such as links inside the tooltip, which users cannot reach because tooltips are not meant to receive focus.
• Using the tooltip as the only label for a control — for example, an icon button with no text that relies entirely on its tooltip for meaning.
• Auto-dismissing the tooltip after a few seconds, which prevents users who read slowly from consuming the content before it disappears.
• Omitting role="tooltip" or the aria-describedby link, so screen readers never read the tooltip content to the user.

Why This Matters

Tooltips are frequently used on icon-only buttons, truncated text, and form field hints — exactly the places where supplemental context is most critical. When a tooltip only works on hover, keyboard users and touch-screen users get no access to that context at all. Worse, when developers use tooltips as the sole label for an unlabeled icon button, the button becomes completely meaningless to any user who cannot trigger the hover state. Proper tooltip implementation is one of the simplest ways to ensure all users have access to the same contextual information.

Accessibility Validation

This component is validated against internal accessibility criteria aligned with WCAG standards, using our internally developed system, Resonance Specs.

To learn more, please contact us.

Code

Reference Implementation

• Back to Home
• GitHub Code