Skip to content
Mosaic
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

GuidancePractice
DoWrap a toolbar of tooltips in Tooltip.Group, so moving between triggers opens the next at once.
DoPass render to Tooltip.Trigger to make an existing Button the trigger.
Don’tPut interactive content in Tooltip.Popup. Use a popover or menu instead.
Don’tRely 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.

PropTypeDescription
openbooleanOpen state, when controlled.
defaultOpenbooleanOpen state on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled 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'
sideOffsetnumberGap in px between trigger and popup.Default: 4
delaynumberMs before opening on hover. Ignored inside Tooltip.Group.Default: 200
closeDelaynumberMs 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.

PropTypeDescription
delaynumber | { open?: number; close?: number }Replaces each member's delay and closeDelay.Default: { open: 200, close: 100 }
timeoutMsnumberMs 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

TSX
<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>