On this page
Tooltip
Headless, unstyled floating label that opens on hover after a delay or on keyboard focus, and closes on leave, blur or Escape. It never takes focus and holds no interactive content.
Use for
- a label for an icon-only button
- the full text of truncated content
- a short hint shown on hover or focus
- a toolbar whose tooltips switch instantly as the pointer moves
Practices
| Guidance | Practice |
|---|---|
| Do | Wrap a cluster of triggers, such as a toolbar, in Tooltip.Group so moving between them switches at once. |
| Do | Pass the trigger’s own button through render instead of nesting a button inside Tooltip.Trigger. |
| Do | Animate the popup with data-starting-style and data-ending-style. |
| Don’t | Put links or buttons in the popup. It cannot be reached by keyboard. Use Popover instead. |
| Don’t | Use the tooltip as a button’s only name. Give the trigger its own aria-label; the tooltip only describes it. |
| Don’t | Pass id to Tooltip.Positioner. The primitive owns it to pair the trigger’s aria-describedby. |
API reference
Tooltip.Root
Holds the open state, position and hover delays. Renders no element. Nested tooltips are supported.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the tooltip is open, when controlled. |
defaultOpen | boolean | Whether the tooltip is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | Placement | Where the tooltip sits relative to the trigger.Default: 'top' |
sideOffset | number | Gap to the trigger in px.Default: 4 |
delay | number | Hover open delay in ms. Ignored inside a Tooltip.Group.Default: 200 |
closeDelay | number | Hover close delay in ms. Ignored inside a Tooltip.Group.Default: 0 |
Tooltip.Group
Shares one delay across the tooltips inside it. Renders no element.
| Prop | Type | Description |
|---|---|---|
delay | number | { open?: number; close?: number } | Open and close delay in ms. Replaces each member’s own.Default: { open: 200, close: 100 } |
timeoutMs | number | How long after a tooltip closes the next one still opens instantly, in ms.Default: 300 |
Tooltip.Trigger
A button with aria-describedby pointing at the tooltip. Carries data-open or data-closed.
Tooltip.Portal
Portals its children while the tooltip is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | RefObject<HTMLElement | null> | The element to portal into.Default: the `Portal` container |
Tooltip.Positioner
The floating div with role="tooltip", rendered only while mounted. Carries data-side and the anchor CSS variables.
Tooltip.Popup
The visible div. Carries data-open, data-closed, data-starting-style and data-ending-style.
Tooltip.Arrow
An optional FloatingArrow svg pointing at the trigger. Carries data-side.
Examples
Icon button tooltip
<Tooltip.Root>
<Tooltip.Trigger render={<IconButton aria-label='Settings' />} />
<Tooltip.Portal>
<Tooltip.Positioner>
<Tooltip.Popup>
Settings
<Tooltip.Arrow />
</Tooltip.Popup>
</Tooltip.Positioner>
</Tooltip.Portal>
</Tooltip.Root>