Tooltip component

Playground

Change a prop on the right and the preview updates. Switch to Code to copy what you see.

Recipes

Copy-paste patterns for the ways Tooltip actually gets used — each one a real, self-contained example.

<Tooltip content="Copy to clipboard">
  <Button isIconOnly variant="ghost" aria-label="Copy">
    <CopyIcon />
  </Button>
</Tooltip>

<Tooltip content="Delete" placement="bottom" showArrow>
  <Button isIconOnly color="danger" variant="ghost" aria-label="Delete">
    <TrashIcon />
  </Button>
</Tooltip>

<Tooltip content="Looks good" color="success">
  <Button variant="bordered">Success</Button>
</Tooltip>
<Tooltip content="Careful" color="warning">
  <Button variant="bordered">Warning</Button>
</Tooltip>

<Tooltip content="Advanced settings" delay={300} closeDelay={100}>
  <Button variant="ghost">Settings</Button>
</Tooltip>

Basic usage

Tooltip takes exactly one child — the trigger — and content for what to show. It opens on hover or keyboard focus and closes on the corresponding leave/blur, so a keyboard-only user reaches it the same way a mouse user does.

<Tooltip content="Copy to clipboard">
  <Button isIconOnly variant="ghost" aria-label="Copy">
    <CopyIcon />
  </Button>
</Tooltip>

Placement

placement supports the full 12-way positioning set (each side, plus start/end variants), with shouldFlip on by default so it automatically switches sides rather than rendering off-screen near a viewport edge. showArrow adds a small pointer connecting the tooltip back to its trigger.

<Tooltip content="Delete" placement="bottom" showArrow>
  <Button isIconOnly color="danger" variant="ghost" aria-label="Delete">
    <TrashIcon />
  </Button>
</Tooltip>

Delay and touch behavior

delay controls how long a hover has to hold before the tooltip opens (0 by default — instant); closeDelay controls how long it stays open after the pointer leaves, and also acts as a floor for touch-triggered opens so a tap-and-release on a touch device doesn't flash the tooltip for an imperceptible instant. This is decided per interaction event, not a single device check, so a device with both touch and mouse input (a touchscreen laptop) gets correct behavior for whichever input actually triggered it.

<Tooltip content="Advanced settings" delay={300} closeDelay={100}>
  <Button variant="ghost">Settings</Button>
</Tooltip>

Controlled visibility

For a tooltip driven by something other than hover/focus (showing it programmatically after an action, keeping it open during a guided tour step), use isOpen + onOpenChange instead of the default uncontrolled hover behavior.

<Tooltip content="Click here to continue" isOpen={tourStep === 2} onOpenChange={setTourVisible}>
  <Button color="primary">Next</Button>
</Tooltip>

Props

The full public API for Tooltip. Every prop is stable and intentionally typed.

Accessibility

• •The trigger must be a real focusable element (a button, a link, an input) — a tooltip attached to a plain, non-interactive text node is unreachable by keyboard, since there's nothing to focus to trigger it.
• •shouldCloseOnBlur (on by default) closes the tooltip the moment its trigger loses focus, so it never lingers open after keyboard focus has moved elsewhere on the page.
• •isKeyboardDismissDisabled turns off Escape-to-close — leave it on (the default) for the vast majority of tooltips; only disable it for a tooltip that's meant to persist regardless of Escape.
• •Tooltip content should be supplementary, not the only place critical information lives — anything a user genuinely needs shouldn't be hidden behind a hover-only interaction.

Best practices

• ◆Always wrap a real interactive element (Button, a link, a native input) — never plain text or a decorative <span> — so the tooltip is reachable by keyboard, not just mouse hover.
• ◆Keep tooltip content short — a sentence at most. Anything longer belongs in a Popover-style pattern with its own dismiss affordance, not a hover tooltip.
• ◆Use a small delay (150-300ms) rather than 0 for tooltips on frequently-hovered UI (a toolbar of icon buttons) — instant tooltips firing on every incidental mouse pass become noisy rather than helpful.
• ◆Reserve controlled isOpen for cases that genuinely need it (guided tours, programmatic hints) — for ordinary hover/focus tooltips, the built-in uncontrolled behavior already handles delay, dismissal, and touch correctly.