Tooltip

A brief hint anchored to a control.

Preview

Design guidance

Use a brief, noninteractive hint for hover or focus. Put controls and longer content in Popover. Icon-only triggers need their own accessible name. Wrap a disabled control in a focusable element when its tooltip explains why it is unavailable.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/tooltip.json

Basic usage

1234567891011import { Tooltip } from "@/components/ui/tooltip";
import { Button } from "@/components/ui/button";

<Tooltip.Root>
  <Tooltip.Trigger render={<Button variant="outline" />}>Copy</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup>Copy answer<Tooltip.Arrow /></Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

Structures

Examples

Basic hint

Use a short label for an icon action.

Keyboard shortcut

Compose Kbd with the hint when the application has that shortcut.

Multiline content

Keep guidance short; longer hints wrap within the available width.

Top

Choose the preferred side; Base UI can adjust it to avoid a collision.

Right

The arrow follows the resolved side.

Bottom

Use the same popup and arrow on each side.

Left

Keep the trigger accessible by keyboard.

Disabled control

A focusable wrapper lets keyboard users read the reason.

API reference

Tooltip properties
Prop	Type	Default	Description
`Root.open / defaultOpen / onOpenChange`	`boolean / boolean / callback`	`uncontrolled, initially closed`	Keeps Base UI controlled and uncontrolled behavior.
`Trigger.render / ref`	`ReactElement \| render function / ref`	`canonical Button`	Caller render wins. The ref accepts HTMLElement, including focusable wrapper elements.
`Positioner.side / align`	`Side / "start" \| "center" \| "end"`	`"top" / "center"`	The resolved side can change to avoid collisions.
`Positioner.sideOffset / alignOffset / arrowPadding`	`number or supported offset function / number`	`8 / 0 / 5`	Positioner owns placement and the arrow gap.
`Popup.className / style / ref`	`Base UI popup props`	`one canonical surface`	State callbacks, refs and render composition remain available.
`Arrow`	`Base UI Arrow props`	`decorative SVG`	Renders a real arrow and follows the resolved side. Custom children/render are supported.
`Popup.role`	`ARIA role`	`"tooltip"`	May be explicitly overridden.
`Provider.delay / closeDelay / timeout`	`number`	`Base UI defaults`	Related tooltip roots can share timing. Trigger hover delay defaults to 600ms; focus opens immediately.
`TooltipProvider.delay / delayDuration`	`number`	`0`	Convenience provider retains immediate hover. Explicit delay wins over delayDuration.
`TooltipTrigger / TooltipContent`	`convenience wrappers`	`same canonical parts`	Content includes Portal, Positioner, Popup and Arrow. Placement props go to Positioner; popup props/ref go to Popup.

Advanced handles, detached triggers and additional parts follow Base UI Tooltip.