semantic pattern · Hover and contextual information
Tooltip
A small, non-interactive text popup that supplements a control when it receives hover or keyboard focus.
Decisive boundary
If users must move into the surface or operate links, use a Popover instead.
Definition and intent
What is a Tooltip UI pattern?
Use the behavior, not the silhouette
A small, non-interactive text popup that supplements a control when it receives hover or keyboard focus. The term is used here as a semantic pattern whose role and interaction contract carry more meaning than its appearance. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Clarify an otherwise understandable control without adding a new task surface. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Tooltip, the boundary is: If users must move into the surface or operate links, use a Popover instead.
Do not implement it as Popover, Hover Card, or Dialog when the content is only a short non-interactive label. If those requirements describe the real task better, use the related pattern page or the full Hover and contextual information comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Clarify an otherwise understandable control without adding a new task surface.
Define opening and closing
Pointer hover and keyboard focus on the owning element. Pointer leave, focus loss, or Escape while open.
Specify access behavior
Focus stays on the owning element; the tooltip itself does not receive focus. Appears on focus and closes with Escape.
Reject the near miss
Popover, Hover Card, or Dialog when the content is only a short non-interactive label.
Behavior contract
What must survive the build
- trigger
- Pointer hover and keyboard focus on the owning element.
- dismissal
- Pointer leave, focus loss, or Escape while open.
- modality
- Non-modal.
- focus
- Focus stays on the owning element; the tooltip itself does not receive focus.
- keyboard
- Appears on focus and closes with Escape.
- interactive
- No interactive controls inside.
- persistence
- Temporary supplementary information.
- placement
- Adjacent to the owning element.
- mobile
- Do not depend on hover; keep an accessible name or visible label available.
Failure modes
Common wrong builds
- Making critical information hover-only.
- Putting buttons or links inside.
- Failing to open on keyboard focus.
Observable checks
Verify the result
- It opens on hover and focus.
- Focus remains on the trigger.
- Escape closes it.
- It contains no interactive controls.
- The trigger still has an accessible name.
Coding-agent handoff
Implementation brief template
Pattern: Tooltip Purpose: Clarify an otherwise understandable control without adding a new task surface. Trigger: Pointer hover and keyboard focus on the owning element. Dismissal behavior: Pointer leave, focus loss, or Escape while open. Modality: Non-modal. Focus behavior: Focus stays on the owning element; the tooltip itself does not receive focus. Keyboard behavior: Appears on focus and closes with Escape. Interactive content: No interactive controls inside. Placement: Adjacent to the owning element. Mobile behavior: Do not depend on hover; keep an accessible name or visible label available. Do not implement as: Popover, Hover Card, or Dialog when the content is only a short non-interactive label. Acceptance checks: - It opens on hover and focus. - Focus remains on the trigger. - Escape closes it. - It contains no interactive controls. - The trigger still has an accessible name.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Tooltip UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Tooltip in web UI?
A small, non-interactive text popup that supplements a control when it receives hover or keyboard focus. In this reference set it is a semantic pattern whose role and interaction contract carry more meaning than its appearance.
When should I use a Tooltip?
Clarify an otherwise understandable control without adding a new task surface. The decisive boundary to confirm is this: If users must move into the surface or operate links, use a Popover instead.
What keyboard and focus behavior does a Tooltip need?
Appears on focus and closes with Escape. Focus stays on the owning element; the tooltip itself does not receive focus. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Tooltip behave on mobile?
Do not depend on hover; keep an accessible name or visible label available. Its modality is a separate requirement: Non-modal.
How do I verify a Tooltip implementation?
Start with observable checks: It opens on hover and focus. Focus remains on the trigger. Escape closes it. Then verify the remaining checks and compare the result with the linked source guidance.