Overview

Use for

Clarifying icon-only buttons and compact controls.
Surface keyboard shortcuts for power users.
Inline help with minimal disruption to layout.

Avoid for

Critical messaging—use Dialog or Alert banners instead.
Content the user must tap to discover on mobile (tooltips are hover-first).
Long-form explanations; keep copy under two sentences.

Examples

Button helper

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from "@/components/ui/tooltip"

export function TooltipExample() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <Button variant="ghost">Hover me</Button>
        </TooltipTrigger>
        <TooltipContent side="bottom">
          Extra context for this action
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

Icon-only trigger

import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"
import { IconQuestionMark } from "@tabler/icons-react"

export function IconTooltip() {
  return (
    <Tooltip>
      <TooltipTrigger className="inline-flex h-6 w-6 items-center justify-center rounded-full bg-surface-2 text-accent">
        <IconQuestionMark size={14} />
      </TooltipTrigger>
      <TooltipContent side="right" sideOffset={4}>
        Tooltips must be triggered by focusable or interactive content.
      </TooltipContent>
    </Tooltip>
  )
}

Props

Prop	Type	Default	Description
`delayDuration`	`number`	200	Delay in ms before the tooltip appears (provider level).
`skipDelayDuration`	`number`	300	Grace period before tooltips reappear as the user moves between triggers.
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	'top'	Preferred side of the tooltip relative to the trigger.
`sideOffset`	`number`	0	Pixel offset from the trigger element.

Accessibility

Keyboard & focus

Triggers must be focusable (buttons, links, or elements with `tabIndex=0`).
Ensure tooltip content is concise; long content will be read aloud on focus.
Keep the provider delay (200ms) to avoid flicker when moving between triggers.

Design cues

Use tooltips to clarify iconography, not to hide critical actions.
Place the arrow using `TooltipArrow` to imply spatial relationship.
For mobile, rely on tap-and-hold or consider inline helper text.