A compact popup that provides a short explanation on hover or keyboard focus.

Use Tooltip to clarify an unfamiliar icon, abbreviation, or compact control. Keep essential instructions visible in the interface instead of hiding them in a tooltip.

Basic tooltip

Installation

$npx shadcn@latest add @patchui/tooltip

The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/tooltip.tsx.

Usage

<TooltipProvider>
  <Tooltip content="Creates a new project">
    <Button variant="secondary">New project</Button>
  </Tooltip>
</TooltipProvider>

Wrap related tooltips in Tooltip Provider to establish consistent timing. Tooltip uses its child as the interactive trigger, so pass one focusable element.

Composition

TooltipProvider
└── Tooltip
    └── Trigger element

Examples

Placement

Tooltip defaults to the top and can be placed on any side of its trigger. The popup adjusts when the requested side lacks room.

Tooltip placement

Tooltips can reinforce accessible names for compact icon controls, but the buttons still need their own labels.

Tooltips in a toolbar

API reference

Prop	Type	Default	Description
content	ReactNode	-	Provides the short explanatory content.
side	"top" \| "right" \| "bottom" \| "left"	"top"	Requests a side of the trigger for placement.
align	"start" \| "center" \| "end"	"center"	Aligns the popup along the selected side.
sideOffset	number	4	Sets the gap between trigger and popup in pixels.
delay / closeDelay	number / number	150 / 0	Controls the opening and closing delay in milliseconds.
TooltipProvider.timeout	number	500	Keeps nearby tooltip interactions within the shared timing window.

Use the exported Tooltip primitives only when the compact content API cannot express the required trigger or controlled behavior.

Accessibility

Tooltip opens for both pointer hover and keyboard focus.
The trigger must remain focusable without relying on Tooltip to add semantics.
Icon-only buttons need an accessible name even when the tooltip repeats that text.
Keep content to a short phrase or sentence. Use Popover for interactive or longer content.