Website tooltips: help that works beyond mouse hover

Choose the pattern before its styling

MDN’s tooltip reference describes a contextual, noninteractive description. The trigger can reference it through aria-describedby; focus stays on the trigger rather than entering the tooltip. The role does not create opening, closing or pointer behaviour.

A panel containing a link, checkbox or close button needs an interaction model that accommodates those controls. Do not put focusable actions inside a tooltip and rely on the name to make the result understandable. Our dialog and popup guide covers a different, deliberately interactive surface.

The APG tooltip page is informative work in progress and explicitly lacks task-force consensus. Treat it as a discussion of behaviour, not a finished implementation to paste into production. Keep the component’s actual content and supported interaction in the review.

Give the trigger meaning without the tooltip

A mysterious question-mark icon creates an additional discovery task. Give the trigger a meaningful name related to its context and inspect its exposed description. Avoid a label made only of punctuation, or a long duplicate description announced several times.

The catalogue could provide a short visible explanation beside Availability instead of adding another control. If a separate help trigger is justified, decide how it is reached and what activating it does. Merely adding tabindex to arbitrary text creates a keyboard stop without necessarily creating an understandable control.

Do not assume an HTML title attribute solves the task. Browser-controlled, unmodified title presentation has an exception within the hover/focus criterion, but that exception does not make title-only essential information a dependable keyboard or touch experience. Use persistent help where the reader needs it.

Keep a usable pointer route into the explanation

W3C’s Content on Hover or Focus explanation describes conditions for dismissing additional content, moving the pointer over it and keeping it available. Its exceptions need interpretation; an ordinary tooltip obscuring meaningful content should not require moving the pointer away just to dismiss it.

Move slowly from the catalogue’s help trigger into the displayed text. A gap that closes the tooltip before the pointer reaches it defeats reading at a comfortable pace. Check the actual rendered boundary, including padding and decorative arrows, rather than only the component’s design file.

Do not impose an arbitrary short reading timer. Keep the explanation available while the relevant hover or focus condition remains, unless it is dismissed or becomes invalid. A chosen opening delay should prevent accidental noise without making deliberate help feel broken; there is no universal delay suitable for every component.

Dismiss without starting a reopening loop

Review Escape as a separate action. Dismissing the help should leave the catalogue usable and focus in its logical place. If focus remains on the trigger, the same focus event should not instantly reopen the content the reader just dismissed.

Ask the maintainer to describe when a new deliberate encounter can show it again. This is state ownership: opening, dismissal and later re-entry must agree. Adding a second generic tooltip script can leave one handler closing the surface while another opens it.

Check competing overlays too. Escape intended for contextual help should not unexpectedly discard an unfinished task in another component. Record the active surface and the expected recipient of the key; do not fix a conflict by disabling every closing route.

Review keyboard and touch as distinct journeys

Reach the help context using the keyboard, confirm the trigger’s visible focus and inspect the description with relevant assistive technology. Continue forward and backward. A noninteractive tooltip should not introduce a hidden sequence of internal Tab stops or move focus into decorative text.

Touch devices do not offer the same dependable hover journey. Keep essential content visible and choose a deliberate alternative if optional help needs activation. A visible short definition or a properly designed disclosure may be simpler than emulating mouse hover. Test what tapping does; avoid a first tap that silently consumes the action a button’s label promises.

Record the browser and input method actually reviewed. A keyboard inspection does not prove a screen-reader announcement, and a desktop pointer check does not establish phone behaviour. For entry instructions, use the separate form-help workflow.

Diagnose clipping and unreadable placement

Increase text size and inspect the narrow layout. The description may wrap beyond its container, cover the trigger or be clipped by an ancestor. Correct the responsible placement rule rather than truncating the explanation until one screenshot looks tidy.

Check triggers near each viewport edge and within scrolling panels. A placement that works in the page centre may fail beside the right edge or a sticky surface. Verify contrast and focus cues against the actual surrounding background using the contrast-state review.