Tooltips surface a small amount of contextual information when operators hover, focus, or long-press a trigger. They reduce visual noise while keeping expert affordances discoverable, and they are explicitly supplementary—if the hint is required to complete the task, it belongs inline, in helper text, or in a Popover. The mental model is "optional reminder," not "place necessary instructions here."
- Icon-only controls that need a name for scanning and screen readers.
- Truncated text where revealing the full string on hover aids verification.
- Short "why disabled" explanations when the reason is secondary to the layout.
- Any hover-only hint that must also appear on keyboard focus for parity.
- Information required to complete the task—put it in the page, helper text, or a
Popover.
- Long or formatted content—use a popover or inline expansion.
- Interactive content (links, inputs)—tooltips cannot hold interactive affordances.
- Touch-primary flows without an alternative path. Many operators never see hover hints.
- One short sentence; two only when unavoidable. Sentence case; no trailing jargon.
- Don't repeat visible labels verbatim. The tooltip should add something.
- Translate via
formatMessage; expect longer strings and verify placement.
- Hover and focus show; blur and Escape hide. Both input modes must reach the tooltip.
- No empty tooltips. If the tooltip would be redundant with the visible label, omit it.
- Don't stack active tooltips in dense tables. Prefer row-level actions with text labels.
Do
- Name every
IconButton accessibly (aria-label), even when a tooltip exists. Tooltips are supplemental.
- Test at viewport edges; allow the placement to flip so the tooltip never extends offscreen.
- Respect reduced-motion preferences.
Don't
- Put passwords, secrets, or PII in tooltips where shoulder-surfing is a concern.
- Keep essential compliance or safety warnings only in tooltips on sensitive flows.
- Let a lingering tooltip layer block clicks beneath it.
Tooltip content must be announced in line with the library's pattern (typically on focus). Don't rely on a tooltip as the only aria-label—triggers still need proper naming. See Accessibility for the full contract.
- Popover for richer or longer hints.
- Icon button for the typical tooltip trigger in dense UI.
