Tooltips

Last updated:

Practical patterns for supplementary hints — keyboard, touch, and without hiding essential information.

01 — Foundation

Tooltips supplement — they do not replace labels

If users must read a tooltip to use the interface, the design has already failed.

Tooltips show brief supplementary text on hover or focus. They are poor containers for essential instructions, form labels, or error messages. Use them sparingly for optional clarification — not as a hiding place for copy the team did not want on screen.

02 — When

Appropriate uses

Prefer visible labels and help text before floating hints.

  • icon buttons with short names — “Settings”, “Close” — where space is tight
  • optional clarification on unfamiliar terms — not the only explanation
  • truncated labels are a layout problem — fix truncation, do not tooltip the full string only on hover
  • for richer help, use visible text, a details block, or a Popover — not a giant tooltip

03 — Implementation

Native and accessible patterns

Keyboard and touch users must receive the same information.

  • title alone is insufficient — no keyboard access, inconsistent timing, poor screen reader support
  • associate with aria-describedby when using custom tooltips; keep described text in the DOM with .vh — not .is_hidden
  • show on keyboard focus, not hover only; dismiss on Escape
  • do not trap focus inside a tooltip — it is not a dialog 
<button type="button" aria-describedby="help-export">
    Export
</button>
<p id="help-export" class="vh">Downloads CSV of the current filter.</p>

04 — Avoid

Common tooltip failures

Hover-only, tiny targets, and tooltips on disabled controls frustrate everyone.

  • no tooltips on disabled buttons — explain why nearby instead
  • touch devices have no hover — provide an alternative or use tap-to-toggle help
  • respect reduced motion; avoid animated tooltip chase cursors
  • ensure sufficient contrast and readable type size

05 — Review

Before you approve

A short checklist for tooltips in code review.

  • essential information is visible without a tooltip
  • keyboard and screen reader users get the same content
  • touch and reduced-motion cases are considered