A React tooltip with a Liquid Glass popup, configurable delay, placement, and an optional arrow.
Tooltip renders the trigger, portal, positioner, glass popup, directional arrow, and content internally. It is a visual hint for sighted pointer and keyboard users, not a replacement for visible labels or accessible descriptions.
Keep the trigger's accessible name aligned with the tooltip content. Icon-only triggers need an aria-label; the tooltip itself is supplementary.
Pass one element as trigger. It must forward props and refs to its root element, as Button does.
side, align, sideOffset, and alignOffset control the preferred position. The tooltip flips or shifts when it would overflow the viewport.
Use open and onOpenChange to control visibility, and set arrow={false} for a flat tooltip.
The tooltip is closed.
delay controls how long the pointer must rest before the tooltip opens; closeDelay controls the closing delay. Both are passed to the Base UI trigger. Set delay={0} for immediate feedback during onboarding, or a longer delay when tooltips appear frequently.
Tooltips are often paired with icon buttons. Give the trigger its own aria-label; the tooltip text is not a substitute for the button's accessible name.
Tooltip opens when the trigger is hovered or receives keyboard focus and closes on blur, Escape, or an outside press. The popup is visual-only: it is not exposed as a description, and tooltips are not available to touch or screen reader users. The trigger must carry its full accessible name from visible text, aria-label, or aria-labelledby.
Tooltip content must be short and supplementary. Do not put interactive controls or unique information inside a tooltip, because some users may never open it. See the accessibility guide for label and focus guidance.
| Prop | Type | Default | Description |
|---|---|---|---|
trigger | ReactElement | — | Element that opens the tooltip. Required. It must forward props and refs. |
children | ReactNode | — | Short hint displayed in the popup. Required. |
arrow | boolean | true | Whether to render the directional arrow. |
delay | number | 600 | Delay before opening on hover, in milliseconds. |
closeDelay | number | 0 | Delay before closing, in milliseconds. |
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "top" | Preferred side of the trigger. |
align | "start" | "center" | "end" | "center" | Alignment relative to the trigger. |
sideOffset | number | OffsetFunction | 8 | Distance between the trigger and popup in pixels. |
alignOffset | number | OffsetFunction | 0 | Offset along the alignment axis in pixels. |
collisionPadding | Padding | 5px per side | Space kept between the popup and the collision boundary. |
open | boolean | — | Controlled open state. |
defaultOpen | boolean | false | Initial open state when uncontrolled. |
onOpenChange | (open: boolean, details) => void | — | Called when the tooltip opens or closes. |
onOpenChangeComplete | (open: boolean) => void | — | Called after the open or close animation finishes. |
disabled | boolean | false | Prevents the tooltip from opening. |
trackCursorAxis | "none" | "x" | "y" | "both" | "none" | Axis the tooltip follows while the pointer moves. |
disableHoverablePopup | boolean | false | Whether the tooltip contents can be hovered without closing the tooltip. |
actionsRef | RefObject<Tooltip.Root.Actions | null> | — | Imperative close and unmount actions. |
triggerId | string | null | — | ID of the trigger for a controlled tooltip. |
defaultTriggerId | string | null | — | ID of the trigger for an initially open tooltip. |
handle | Tooltip.Handle<Payload> | — | Handle that lets external triggers control the tooltip. |
className | string | — | Tailwind classes merged into the popup. |
style | CSSProperties | — | Inline styles merged into the same element as className. |
ui | { positioner?: ClassValue; popup?: ClassValue; glass?: ClassValue; overlay?: ClassValue; arrow?: ClassValue; content?: ClassValue } | — | Tailwind classes for internal slots, keyed by data-slot. |
ui keys map to the data-slot values listed below. Additional Base UI Tooltip.Root props are forwarded.
| Attribute | Description |
|---|---|
data-open | Present when the popup is open. |
data-closed | Present when the popup is closed. |
data-side | Indicates the resolved side (top, bottom, left, right, inline-start, or inline-end). |
data-align | Indicates the resolved alignment (start, center, or end). |
data-starting-style | Present when the popup begins animating in. |
data-ending-style | Present when the popup is animating out. |
data-instant | Present when animations should be skipped. |
data-popup-open | Present on the trigger while the tooltip is open. |
data-slot | Marks internal parts (positioner, popup, glass, overlay, arrow, content). |
The component uses the shared glass material. Tune shared --ui-glass-* tokens on a parent, use className for layout, and use ui for internal slots keyed by data-slot. Component-specific values live in src/theme/tooltip.ts. See the theming guide for token layers and presets.