Tooltip
Displays a small floating text bubble when users hover over or focus on an element, explaining what that button or icon does.
3 KB
•Updated on August 21, 2026
Installation
Bash
pnpm dlx shadcn@latest add @spaceui/primitives-tooltipUsage
Code
import { Tooltip, TooltipCreateHandle, TooltipPopup, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'Code
<Tooltip>
<TooltipTrigger render={<Button variant="outline" />}>Hover me</TooltipTrigger>
<TooltipPopup>Helpful hint</TooltipPopup>
</Tooltip>Anatomy
Code
<Tooltip>
<TooltipTrigger />
<TooltipPopup />
</Tooltip>Accessibility
- Follows the WAI-ARIA Tooltip Pattern.
- Appears on hover and focus without stealing focus from the trigger.
Keyboard Interactions
| Key | Action |
|---|---|
| Escape | Immediately dismisses the visible tooltip. |
API Reference
Tooltip
Root component. Alias for Tooltip.Root from Base UI.
TooltipTrigger
Trigger element that shows the tooltip on hover/focus. Alias for Tooltip.Trigger from Base UI.
TooltipPopup
Popup container that displays the tooltip content. Also exported as TooltipContent.
| Prop | Type | Default | Description |
|---|---|---|---|
side | top|bottom|left|right | top | Side of the trigger to position the tooltip |
align | start|center|end | center | Alignment relative to the trigger |
sideOffset | number | 4 | Distance from the trigger in pixels |
anchor | Element|null|React.RefObject<Element> | - | Custom anchor element or ref to anchor the tooltip against |
portalProps | Tooltip.Portal.Props | - | Props forwarded to the internal portal (keepMounted, container, etc.); see Base UI Tooltip portal API |
TooltipProvider
Provider for grouping tooltips. Alias for Tooltip.Provider from Base UI.
TooltipCreateHandle
Creates a handle for detached tooltip triggers. Returns a handle object to attach to multiple triggers for animated transitions.
Examples
Grouped tooltips
Toggle group animated tooltip
Vertical group with animated tooltip