Tooltip

A short contextual hint for icon controls, status details, timestamps, and compact metadata.

Anatomy#

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.

Action cluster#

Status hint#

Thinking

Icon content#

Long text#

Long text with icon#

Timestamp detail#

Today at 09:30

Shortcut hint#

Arrow placement#

Brutal renders tooltip hints without arrows.

Thinking09:30

API#WIP

TooltipProvider#

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.

Tooltip#

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.

TooltipTrigger#

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.

TooltipPortal#

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.

TooltipContent#

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 elegant, 6 brutal	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.