On this page
Tooltip
A short label that shows on hover or focus of its trigger, and closes on Escape. Styled over the headless Tooltip primitive; the popup portals and positions itself.
Use for
- a label for an icon-only control
- a short hint on hover or focus
- a row of toolbar tooltips that open at once after the first
Practices
| Guidance | Practice |
|---|---|
| Do | Wrap a toolbar of tooltips in Tooltip.Group, so moving between triggers opens the next at once. |
| Do | Pass render to Tooltip.Trigger to make an existing Button the trigger. |
| Don’t | Put interactive content in Tooltip.Popup. Use a popover or menu instead. |
| Don’t | Rely on a tooltip as the only accessible name of an icon-only button. Give the button its own name with VisuallyHidden or aria-label. |
API reference
Tooltip.Root
Holds the open state and positioning. Renders no element.
| Prop | Type | Description |
|---|---|---|
open | boolean | Open state, when controlled. |
defaultOpen | boolean | Open state on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | 'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | Preferred side and alignment. Flips and shifts to stay in view.Default: 'top' |
sideOffset | number | Gap in px between trigger and popup.Default: 4 |
delay | number | Ms before opening on hover. Ignored inside Tooltip.Group.Default: 200 |
closeDelay | number | Ms before closing on hover out. Ignored inside Tooltip.Group.Default: 0 |
Tooltip.Group
Shares one delay across the tooltips inside, so once one opens the next opens at once.
| Prop | Type | Description |
|---|---|---|
delay | number | { open?: number; close?: number } | Replaces each member's delay and closeDelay.Default: { open: 200, close: 100 } |
timeoutMs | number | Ms after the last close before the group waits for the delay again.Default: 300 |
Tooltip.Trigger
A button (type='button') wired to open the tooltip and described by it. Carries data-open or data-closed.
Slot: cl-tooltip-trigger
Tooltip.Popup
The label, as role="tooltip". Portals, and sits in a positioner (cl-tooltip-positioner) with data-side. Mounts only while open.
Slot: cl-tooltip-popup
Examples
An icon button with a tooltip
<Tooltip.Root>
<Tooltip.Trigger render={<Button variant='ghost' shape='square' />}>
<Icon glyph={Copy} />
<VisuallyHidden>Copy</VisuallyHidden>
</Tooltip.Trigger>
<Tooltip.Popup>Copy</Tooltip.Popup>
</Tooltip.Root>