Tooltip

Tooltip Variants

Placement Variants

Arrow / No Arrow

• With arrow: Points to the trigger element. Clarifies association.
• Without arrow: Cleaner look. Common in modern design systems (Shadcn, Radix default).

Delay Behavior

Tooltip Properties

Design Token Mappings

Tooltips on dark backgrounds need inverted tokens. Verify tooltip text contrast with our Contrast Checker — white text on gray-900 typically achieves 15:1+, but custom colors may not.

Tooltip States

Positioning & Collision

When a tooltip's preferred position would overflow the viewport:

1. Flip: Switch to the opposite side (top ↔ bottom, left ↔ right)
2. Shift: Slide along the axis to stay in bounds while keeping the same side
3. Auto: Let the positioning engine (Floating UI / Popper) choose the best placement

This collision detection is handled automatically by libraries like Floating UI. Don't build it yourself — edge cases are numerous and subtle.

WCAG Requirements

ARIA Implementation

For naming tooltips (icon buttons):

<!-- Option A: aria-label on the trigger -->
<button type="button" aria-label="Delete item">
  <svg aria-hidden="true"><!-- trash icon --></svg>
</button>
<!-- Tooltip appears on hover but is decorative — screen readers use aria-label -->

<!-- Option B: aria-describedby linking to tooltip -->
<button type="button" aria-describedby="tooltip-delete">
  <svg aria-hidden="true"><!-- trash icon --></svg>
</button>
<div role="tooltip" id="tooltip-delete">Delete item</div>

For supplementary tooltips (additional context):

<span tabindex="0" aria-describedby="tooltip-sla">SLA</span>
<div role="tooltip" id="tooltip-sla">Service Level Agreement</div>

Key decisions:

• role="tooltip" — Tells assistive tech this is a tooltip. Used with aria-describedby.
• aria-describedby — Links the trigger to the tooltip. Content is announced as a description (after the element's name and role).
• Don't use aria-labelledby with role="tooltip" for naming — use aria-label directly on the trigger instead. It's simpler and more reliable.

Keyboard Interaction

Touch Device Considerations

Tooltips fundamentally don't work on touch devices — there is no "hover" interaction. Strategies:

1. Skip tooltips on touch — ensure all critical info is available without them
2. Tap-to-toggle — first tap shows tooltip, second tap activates the button. Bad UX, confusing double-tap.
3. Use a Popover instead — triggered by tap, dismissed by tap outside. This is the best approach for mobile.
4. Long-press — show tooltip on long-press. Discoverable only by convention.

For tooltip accessibility patterns, see our ARIA Attributes Guide and WCAG Practical Guide.

Do's

• ✅ Keep tooltip text to 1–2 short sentences maximum. If you need more, use a Popover.
• ✅ Add a hover delay (200–400ms). Without it, tooltips flash constantly as users move their mouse across the page. Annoying.
• ✅ Make tooltips hoverable (SC 1.4.13). Users should be able to move their cursor from the trigger to the tooltip without it disappearing. This is essential for users with motor impairments.
• ✅ Provide keyboard access. Tooltips must show on focus, not just hover. tabindex="0" if the trigger isn't natively focusable.
• ✅ Use Escape to dismiss. Required by WCAG and expected by keyboard users.

Don'ts

• ❌ Don't put interactive content in tooltips. Links, buttons, form controls — none of these belong in a tooltip. Use a Popover for interactive overlays.
• ❌ Don't use tooltips for form validation. Error messages must be persistent and visible without hovering. Use inline error text.
• ❌ Don't repeat the visible label. If a button says "Save", a tooltip that also says "Save" is redundant noise.
• ❌ Don't use tooltips as a crutch for bad UX. If users constantly need tooltips to understand your interface, the interface is the problem — not the absence of tooltips.
• ❌ Don't show tooltips on disabled elements without careful consideration. If you do, explain why it's disabled ("Requires admin permissions").

Content Guidelines

• Naming tooltips: Match the accessible name exactly — "Delete", "Copy link", "Open settings".
• Supplementary tooltips: One sentence, no period. "Last updated 3 hours ago" not "This shows when the item was last updated by a team member."
• Keyboard shortcuts: Format consistently — "Copy (⌘C)" or "Copy · ⌘C". Use the correct modifier for the platform (⌘ on Mac, Ctrl on Windows).

Cross-System Comparison

Notable Approaches

Radix Tooltip introduces the concept of TooltipProvider — a wrapper that manages the "skip delay" behavior across all tooltips in your app. When a user hovers over one tooltip trigger and then quickly moves to another, the second tooltip appears instantly (no delay). This creates a fluid experience when exploring toolbar buttons. It's a small detail that dramatically improves usability.

Material 3 distinguishes between "Plain Tooltips" (label text only, for icon buttons) and "Rich Tooltips" (title + description + optional action, for detailed information). This formalization is valuable — most design systems blur the line between tooltip and popover. Material makes it explicit: if it has interactive content, it's not a tooltip.

Shadcn/ui wraps Radix's tooltip primitive with Tailwind styling and sensible defaults. The animation uses Tailwind's animate-in / animate-out classes with directional slide based on placement. It's clean and performant.

Ant Design is the most permissive — it allows any ReactNode as tooltip content, including links and interactive elements. This technically violates WCAG SC 1.4.13 guidelines (tooltip content should be non-interactive) and the WAI-ARIA tooltip pattern. If you need interactive content, use Ant's Popover instead.

CSS-only tooltips are tempting but limited. They can't handle collision detection (flipping when near viewport edge), can't be made keyboard-accessible without JavaScript (need Escape to dismiss per SC 1.4.13), and can't implement the hover-over-tooltip requirement. Use them only for decorative, non-essential enhancements.