Tooltip

A small floating label that reveals on hover or focus. Wrap your app in TooltipProvider, then use Tooltip/TooltipTrigger/TooltipContent per tooltip.

Icon-button labels

Placement

With keyboard shortcut

Installation

pnpm

pnpm dlx @hex-core/cli add tooltip

With keyboard shortcut hint

Pair the description with a <kbd> rendering of the shortcut so users discover the hotkey alongside the action

tsx

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="outline" size="icon" aria-label="Open command palette">
        ⌘
      </Button>
    </TooltipTrigger>
    <TooltipContent className="flex items-center gap-2">
      <span>Open command palette</span>
      <kbd className="rounded border bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
        ⌘K
      </kbd>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

Tooltip on a disabled control

Disabled buttons swallow pointer events, so wrap them in a focusable span — the wrapper receives hover/focus and the tooltip explains why the action is unavailable

tsx

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <span tabIndex={0} className="inline-block">
        <Button disabled aria-disabled="true">
          Publish
        </Button>
      </span>
    </TooltipTrigger>
    <TooltipContent>
      <p>Add a title and at least one section before publishing.</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

API Reference

Prop	Type	Default	Description
`delayDuration`	`number`	700	[TooltipProvider prop] Milliseconds before the tooltip appears on hover
`disableHoverableContent`	`boolean`	false	[TooltipProvider prop] When true, tooltip dismisses when cursor enters it
`open`	`boolean`	—	[Tooltip root prop] Controlled open state
`defaultOpen`	`boolean`	false	[Tooltip root prop] Default open state for uncontrolled usage
`onOpenChange`	`function`	—	[Tooltip root prop] Callback on open state change: (open: boolean) => void

AI Guidance

When to use

Use for terse hover/focus-reveal info: icon button labels, abbreviation expansions, keyboard shortcut hints. Content should fit in one line.

When not to use

Don't use for rich content with images or actions (use HoverCard or Popover). Don't use for the only way to convey essential info — it's invisible to touch users.

Common mistakes

Forgetting TooltipProvider at the app root
Tooltip content too long (keep it under one line)
Using Tooltip as the only label for icon buttons (still add aria-label)
Triggering tooltips on non-interactive elements

Accessibility

Triggers on focus and hover. Radix sets role='tooltip' and aria-describedby. Still pair icon buttons with aria-label since tooltips don't announce on touch.

Related components

Token budget: 300

Verified against @hex-core/components@1.12.0

Edit this page on GitHub