Tooltip

Content Guidelines

Keep tooltip text concise — ideally one line, two at most. Tooltips should provide supplementary context, not essential information. Avoid placing interactive content (links, buttons) inside tooltips. If you need more than a short label, consider using Popover instead.

Timing & Delay

The default delayDuration is 0ms for instant feedback. For toolbar-style interfaces with many icon buttons, use delayDuration={400} to avoid tooltips firing during rapid mouse movement. The skipDelayDuration (300ms default) lets users move between triggers without re-incurring the delay.

Placement & Positioning

Default placement is side="top". Tooltips automatically flip to the opposite side when they would overflow the viewport. Use sideOffset to add breathing room between the trigger and tooltip. Ensure tooltips do not obscure related content the user is trying to read.

Color & Contrast

The tooltip uses bg-foreground with text-background for an inverted high-contrast appearance. The arrow inherits fill-foreground to match the tooltip body. This inverted scheme ensures tooltips are visually distinct from surrounding UI and meet WCAG 2.1 AA contrast requirements in both light and dark modes.

Keyboard Navigation

• Tab — Move focus to the tooltip trigger; tooltip appears on focus
• Escape — Dismiss an open tooltip immediately
• Enter or Space — Activates the trigger element (button behavior preserved)
• No keyboard shortcut to explicitly open — tooltips appear on focus automatically

Screen Reader Support

• Tooltip content is announced via aria-describedby on the trigger
• For icon-only buttons, add an explicit aria-label to the trigger for the primary label
• The tooltip acts as supplementary description, not a replacement for visible labels
• Content is announced when the tooltip opens, giving screen reader users the same info as sighted users

Focus Management

Tooltips open on focus and close on blur without stealing focus from the trigger. The tooltip content is not focusable — focus remains on the trigger element. This ensures keyboard users can tab through the interface naturally. Built on Radix UI Tooltip primitive, which manages aria-describedby associations automatically.

Motion & Reduced Motion

Tooltips animate with fade-in/zoom-in on open and reverse on close. When prefers-reduced-motion is active, animations are suppressed and the tooltip appears immediately. Slide-in direction varies by placement side for natural movement.

ARIA Patterns

{/* Basic tooltip - automatically wires aria-describedby */}
<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="outline">Save</Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>Save your changes (Ctrl+S)</p>
  </TooltipContent>
</Tooltip>

{/* Icon-only button with tooltip as accessible label */}
<Tooltip>
  <TooltipTrigger asChild>
    <Button size="icon" variant="outline" aria-label="Add to favorites">
      <HeartIcon className="size-4" />
    </Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>Add to favorites</p>
  </TooltipContent>
</Tooltip>

{/* Disabled trigger - wrap in span for hover events */}
<Tooltip>
  <TooltipTrigger asChild>
    <span tabIndex={0}>
      <Button disabled>Disabled action</Button>
    </span>
  </TooltipTrigger>
  <TooltipContent>
    <p>You need permission to perform this action</p>
  </TooltipContent>
</Tooltip>