Tooltip
A short contextual hint for icon controls, status details, timestamps, and compact metadata.
Controls
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "raft-ui";
<TooltipProvider>
<Tooltip>
<TooltipTrigger />
<TooltipContent />
</Tooltip>
</TooltipProvider>Use Tooltip for terse labels or hidden detail. Rich cards with actions, avatars, or structured content should stay in Popover or a future HoverCard-style primitive. Wrap tooltip trees in TooltipProvider once near the app or page root.
Thinking
Thinking
Tooltips default to collisionAvoidance={{ side: "flip", align: "shift" }}. When a trigger touches an edge boundary, the floating layer automatically flips to the opposite side and shifts along the perpendicular axis to prevent truncation.
Boundary: Dashed box below (tooltips flip & shift at edges)
collisionAvoidance: flip + shift
delaydefault: 0number
Shared open delay in milliseconds. Raft defaults this to immediate hints.
closeDelaynumber
Shared close delay in milliseconds.
timeoutdefault: 400number
Window where adjacent tooltips open instantly after another tooltip closes.
| Prop | Type | Default | Description |
|---|---|---|---|
delay | number | 0 | Shared open delay in milliseconds. Raft defaults this to immediate hints. |
closeDelay | number | — | Shared close delay in milliseconds. |
timeout | number | 400 | Window where adjacent tooltips open instantly after another tooltip closes. |
openboolean
Controlled open state. Pair with onOpenChange.
defaultOpendefault: falseboolean
Initial open state for uncontrolled usage.
onOpenChange(open, eventDetails) => void
Called when hover, focus, press, escape, or disabled state changes visibility.
disableddefault: falseboolean
Prevents the tooltip from opening.
disableHoverablePopupdefault: falseboolean
When true, the popup cannot be hovered without closing.
trackCursorAxisdefault: "none""none" | "x" | "y" | "both"
Moves the tooltip with the cursor when cursor tracking is needed.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Controlled open state. Pair with onOpenChange. |
defaultOpen | boolean | false | Initial open state for uncontrolled usage. |
onOpenChange | (open, eventDetails) => void | — | Called when hover, focus, press, escape, or disabled state changes visibility. |
disabled | boolean | false | Prevents the tooltip from opening. |
disableHoverablePopup | boolean | false | When true, the popup cannot be hovered without closing. |
trackCursorAxis | "none" | "x" | "y" | "both" | "none" | Moves the tooltip with the cursor when cursor tracking is needed. |
renderReactElement | (props, state) => ReactElement
Compose the trigger with Button, time, span, or another focusable element.
delaynumber
Per-trigger open delay override in milliseconds.
closeDelaynumber
Per-trigger close delay override in milliseconds.
payloadunknown
Payload passed to render-function tooltip content when using shared handles.
...propsBase UI Tooltip.Trigger.Props
Native button props plus Base UI trigger behavior.
| Prop | Type | Default | Description |
|---|---|---|---|
render | ReactElement | (props, state) => ReactElement | — | Compose the trigger with Button, time, span, or another focusable element. |
delay | number | — | Per-trigger open delay override in milliseconds. |
closeDelay | number | — | Per-trigger close delay override in milliseconds. |
payload | unknown | — | Payload passed to render-function tooltip content when using shared handles. |
...props | Base UI Tooltip.Trigger.Props | — | Native button props plus Base UI trigger behavior. |
containerHTMLElement | RefObject | null
Custom portal container for framed previews or contained overlays.
...propsBase UI Tooltip.Portal.Props
Portals the tooltip to the body or a custom container.
| Prop | Type | Default | Description |
|---|---|---|---|
container | HTMLElement | RefObject | null | — | Custom portal container for framed previews or contained overlays. |
...props | Base UI Tooltip.Portal.Props | — | Portals the tooltip to the body or a custom container. |
sidedefault: "top""top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"
Preferred side. Tooltip shifts within that side instead of flipping position.
aligndefault: "center""start" | "center" | "end"
Alignment against the trigger.
sideOffsetdefault: 8number
Distance from the trigger edge, passed to Base UI Positioner.
alignOffsetdefault: 0number
Distance along the aligned axis, passed to Base UI Positioner.
portalPropsTooltipPortalProps
Portal options, including a custom container for framed previews or overlays.
...propsBase UI Tooltip.Popup.Props
Popup attributes and event handlers.
| Prop | Type | Default | Description |
|---|---|---|---|
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "top" | Preferred side. Tooltip shifts within that side instead of flipping position. |
align | "start" | "center" | "end" | "center" | Alignment against the trigger. |
sideOffset | number | 8 | Distance from the trigger edge, passed to Base UI Positioner. |
alignOffset | number | 0 | Distance along the aligned axis, passed to Base UI Positioner. |
portalProps | TooltipPortalProps | — | Portal options, including a custom container for framed previews or overlays. |
...props | Base UI Tooltip.Popup.Props | — | Popup attributes and event handlers. |