Tooltip UI Design: When to Use Them, How to Build Them, and the Patterns That Cause More Problems Than They Solve
Author
The tooltip is the most frequently misused UI component in product design. Teams add tooltips when labels are unclear, icons are ambiguous, interactions are confusing, or they simply cannot decide whether to show text on screen. The tooltip becomes the answer to every “maybe the user won’t understand this” question.
The result is interfaces where users must hover over nearly everything to understand what it does, where tooltips appear on elements that do not need explanation, and where genuinely confusing interactions get a tooltip rather than a redesign.
After 20 years of designing digital products, the most reliable signal that an interface has a design problem is excessive tooltip density. Tooltips are a secondary communication layer. They should not be carrying the primary one.
What a tooltip is and what it is not
A tooltip is a small informational overlay that appears when a user hovers over or focuses on a UI element. It provides supplementary context that does not need to be visible all the time: a label for an icon, the full text of a truncated item, a keyboard shortcut, or a brief clarification of what a control does.
The defining characteristic of a tooltip: it is triggered by hover or focus and dismissed when the user moves away. It does not require a click to open or dismiss.
Tooltip vs popover: the distinction that most teams get wrong
Tooltips and popovers serve different functions. Conflating them produces UI that behaves unexpectedly and fails accessibility tests.
A tooltip contains non-interactive text. It cannot contain buttons, links, form fields, or any element the user needs to click or interact with. If the content needs interaction, it is not a tooltip — it is a popover. The popover UX guide covers the popover pattern in full detail.
A tooltip is always triggered by hover or focus. It is never triggered by a click.
A tooltip is always dismissed by moving focus or the cursor away from the trigger. It is never dismissed by pressing Escape alone (though Escape should also dismiss it for keyboard users).
The test for whether you need a tooltip or a popover: can the user accomplish everything they need from the overlay without clicking anything inside it? If yes, it might be a tooltip. If no, it is a popover.
When a tooltip is the right design answer
Tooltips belong in three specific contexts. Outside these contexts, they are either unnecessary or a sign that the underlying interface needs to be redesigned.
Labeling icon-only buttons
Icon buttons without visible labels depend on the user recognizing the icon’s meaning from prior experience. Many icons are sufficiently conventional that most users recognize them without assistance: a magnifying glass for search, a gear for settings, and a trash can for delete. Many are not: a chevron that could mean expand, collapse, or navigate; a grid that could mean layout, apps, or view options.
For icon buttons whose icons are not universally recognizable, a tooltip label is both appropriate and necessary. The tooltip should contain the button’s name, not a description of the action. “Delete” rather than “Click to delete this item.”
For icon buttons where the icon is recognizable to your specific user base (this requires knowing your users, not assuming), the tooltip is optional but still useful for discoverability.
Showing keyboard shortcuts
Keyboard shortcut disclosure is one of the most legitimate uses of tooltips in SaaS products. A user hovering over the “Bold” button in a text editor sees the tooltip “Bold (Cmd+B).” They learn the shortcut at the moment of maximum relevance: when they are about to use the action.
This pattern converts users from click-based to keyboard-based interaction over time, improving their experience, speed, and satisfaction with the product.
Displaying truncated text in full
When a table cell, list item, or label is truncated with an ellipsis due to space constraints, a tooltip can display the full text on hover. This is a data accessibility pattern: users who need the full value can access it without navigating to a different view.
For this use case, the tooltip content should be the full text of the truncated item and nothing else.
When a tooltip is the wrong design answer
The three situations where a tooltip signals a design problem that needs to be fixed at the source rather than papered over with an overlay:
When the primary label or element name is unclear
If users hover over the “Process” button to see what it does, the label is unclear. The tooltip “Processes your selected items for export” reveals that the button name is the problem, not the user’s knowledge. The solution is a clearer button label, not a tooltip that carries the actual meaning.
Tooltips should not be the primary communication of what an element does. The label, icon, or context should handle that. The tooltip should provide supplementary detail: a keyboard shortcut, a brief expansion, a clarification for an edge case.
When the interface is complex, and the tooltip density is high.
A screen where nearly every element has a tooltip is too cluttered with unexplained elements. Tooltip density is inversely proportional to interface clarity. The right response to high tooltip density is not to improve the tooltips. It is worth asking why so many elements need explanation.
If more than 30% of interactive elements on a screen have tooltips, the screen needs a structural redesign. Tooltips should be the exception, not the norm.
When the content needs an interaction
If the tooltip content contains a link, a button, a form field, or any other interactive element, it is not a tooltip. Tooltip content is read-only. If users need to interact with the overlay content, use a popover instead.
Tooltip states that it must be designed.
A tooltip has more states than most teams account for. Designing only the default visible state results in a component that behaves unexpectedly during keyboard navigation, in mobile contexts, and in accessibility testing.
Default hidden
The tooltip trigger element is visible, but no tooltip is displayed. No visual indication that a tooltip exists except for the cursor change on hover (pointer cursor for interactive elements).
Hover visible
The mouse cursor has been over the trigger for the configured delay period (typically 300 to 500ms), and the tooltip is now visible. The tooltip should appear in a position that does not obscure adjacent important content.
Focus visible
A keyboard user has navigated to the trigger element, and the tooltip is visible via focus rather than hover. The tooltip must be visible on focus, not only on hover. This is a WCAG 2.1 Success Criterion 1.4.13 requirement: content that appears on hover must also appear on focus.
Loading state
If the tooltip contains dynamically loaded content (less common but occurs for tooltips showing live data, like user profile previews or link previews), a loading state should be designed: a skeleton or spinner inside the tooltip wrapper while the content is fetching.
Forced visible (for testing and documentation)
Not a user-facing state, but a design system requirement: the tooltip should support a forced-visible variant for use in design documentation and Storybook stories where hover cannot be simulated statically.
Tooltip positioning and collision detection
Tooltip placement is not just a visual decision. It is a usability and engineering decision that must account for viewport boundaries, adjacent content, and the trigger element's position on screen.
Default positioning: above the trigger element, centered horizontally, with 8px of gap between the trigger and the tooltip. Above is the conventional default because it does not cover the content the user is likely looking at (the trigger).
Fallback positioning (collision detection): when the tooltip in its default position would appear outside the viewport, it should automatically flip or shift. The positioning library (Floating UI, Popper.js, or native CSS Anchor Positioning) handles this. The design specification should define the fallback order: above first, then below, then left, then right.
Edge cases to design explicitly:
Tooltips for elements in the top row of a table or screen where “above” positioning clips at the viewport edge: the tooltip should flip to below.
Tooltips for elements in the rightmost position where the tooltip’s natural right edge clips: the tooltip should shift left to remain fully visible.
Tooltips in scroll containers where the trigger element scrolls out of view: the tooltip should dismiss, not follow the trigger off-screen.
Accessibility requirements for tooltips
Tooltips have specific WCAG requirements that most SaaS implementations fail. The failures are almost always caught only during formal accessibility audits, after the component has been built and deployed.
ARIA role and labeling
There are two correct implementations for a tooltip, depending on whether the tooltip content supplements or replaces the accessible name of the trigger.
When the tooltip provides the accessible name for an icon-only button:
When the trigger has its own visible label and the tooltip provides supplementary information:
The role="tooltip" tells assistive technologies that this element is a tooltip, not a general content region. The aria-describedby attribute on the trigger connects the tooltip to the element it describes.
Keyboard behavior
The tooltip must appear when the trigger receives keyboard focus. This is non-negotiable for WCAG 2.1 SC 1.4.13 compliance. Tooltips that appear only on hover are inaccessible to keyboard-only users.
The tooltip must be dismissible by pressing Escape without moving focus away from the trigger. This allows keyboard users to hide the tooltip and continue navigating without losing their place in the tab order.
The tooltip content itself must not be reachable by keyboard focus. Tooltip content is read-only and not interactive. If the content needs to be keyboard-reachable, it must be a popover, not a tooltip.
WCAG 1.4.13 compliance
WCAG 2.1 Success Criterion 1.4.13 (Content on Hover or Focus) requires that content triggered on hover or focus meets three conditions:
Dismissible: users can dismiss the tooltip without moving the pointer or keyboard focus (Escape key).
Hoverable: users can move the pointer over the tooltip without it dismissing. This is required because users with low vision may zoom the viewport and need to move their pointer to read the tooltip text.
Persistent: the tooltip remains visible until the pointer leaves the trigger or tooltip area, focus moves away, or the user dismisses it. It must not auto-dismiss after a timeout.
The auto-dismiss tooltip (visible for 3 seconds, then disappears) fails WCAG 1.4.13. If users need time to read the tooltip content, the auto-dismiss timer prevents them from doing so.
Color contrast
Tooltip text must meet WCAG 2.1 AA contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px or 14px bold). Most dark-background tooltips with white text pass. Most light-background tooltips with gray text do not, particularly at the 12px-14px sizes that tooltips typically use.
Check contrast at the exact tooltip background color and text color combination, not at the page-level color system. Tooltips often use slightly different values from the main design system, and those values may not have been checked.
Tooltip timing and animation
Tooltip appearance should not be immediate. A tooltip that fires the instant the cursor enters the trigger area creates visual noise for users who are simply moving the cursor across the screen.
Hover delay: 300 to 500ms between cursor entry and tooltip appearance. This filters out cursors in transit. Users who intend to interact with a control will pause long enough for the tooltip to appear.
Dismiss delay: zero to 100ms after the cursor leaves the trigger. The tooltip should disappear quickly. Lingering tooltips feel sticky and cover adjacent content.
Animation: a simple fade-in at 100 to 150ms is appropriate. The tooltip should not slide, bounce, or perform any animation that delays the display of its content. The goal is speed, not visual interest.
No animation for users who prefer reduced motion. Implement @media (prefers-reduced-motion: reduce) with a zero-duration transition: the tooltip appears and disappears instantly.
Mobile tooltip design
Hover events do not exist on touch interfaces. Tooltips designed for hover-triggered display must have a fallback strategy for mobile users.
The options:
Remove the tooltip and make the label visible by default on mobile. If the tooltip text is important enough to show users, it is important enough to show without requiring a hover interaction that does not exist on touch.
Replace the tooltip with a long-press disclosure. On mobile, long-pressing an element can trigger a tooltip-like overlay. This is less common and should be reserved for cases where the tooltip is genuinely supplementary and not required for basic usability.
For icon-only buttons on mobile: the label should be visible by default below the icon, not behind a tooltip. A 44px touch target with a visible label is significantly more usable than an icon that reveals its name via hover that never fires.
Common tooltip design failures
After 20 years of auditing SaaS products, these are the patterns that appear repeatedly and consistently degrade user experience:
Tooltip on the tooltip. Nested information hierarchies where a tooltip trigger appears inside another tooltip’s content. This creates UI that is impossible to interact with without accidentally dismissing the parent layer.
Tooltips on disabled elements without explanation. A disabled button with a tooltip explaining why it is disabled is appropriate. A disabled element with no tooltip and no other explanation is an accessibility failure and a UX failure. If a tooltip is warranted for a disabled element, it should explain what the user must do to enable it.
Tooltips that duplicate the label. A button labeled “Export” with a tooltip that says “Export” provides no information. Every tooltip should add information not already visible on screen.
Multi-paragraph tooltips. Tooltips should contain one to two sentences maximum. If the explanation requires more than two sentences, it belongs in documentation, a help article, or an in-product coach mark, which can display more content without being hidden when the user moves their mouse.
Tooltips on every table row action. A table with edit, duplicate, and delete actions in each row does not need tooltips on all three if those actions are recognizable from their icons and the action names are shown on hover. Over-tooltipping dense interfaces reduces performance and adds visual noise.
Frequently asked questions
What is the difference between a tooltip and a popover?
A tooltip contains non-interactive text and is triggered by hover or focus. It cannot contain buttons, links, or form fields. A popover can contain interactive content (buttons, links, form fields) and is typically triggered by a click. If the user needs to interact with the overlay content, use a popover. If the content is read-only supplementary information, use a tooltip. See Foundey’s popover UX guide for the full popover pattern.
When should you use a tooltip in a SaaS product?
Three contexts: labeling icon-only buttons where the icon is not universally recognizable, displaying keyboard shortcuts adjacent to the action they trigger, and showing truncated text in full when space constraints require an ellipsis. Outside these contexts, a tooltip is usually either unnecessary or a sign that the primary interface element needs a clearer label.
What ARIA attributes does a tooltip need?
The tooltip container needs role="tooltip" and an id. The trigger element needs aria-describedby referencing the tooltip’s id. If the tooltip provides the accessible name for an icon-only button (the button has no visible label), the trigger also needs aria-label. The tooltip must appear on keyboard focus (not only hover) to meet WCAG 2.1 SC 1.4.13.
Should tooltips appear immediately on hover?
No. Use a 300 to 500ms hover delay to filter out cursors in transit. Tooltips that appear immediately on any hover create visual noise for users moving across the interface. The delay ensures only users who pause over an element (indicating interest) see the tooltip.
Can tooltips contain links or buttons?
No. Tooltip content is non-interactive by definition. A tooltip that contains a clickable element fails accessibility requirements and creates interaction inconsistencies (users cannot reach the tooltip content with the keyboard). If the overlay needs to contain interactive content, use a popover instead.
