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

GuidancePractice
DoWrap a cluster of triggers, such as a toolbar, in Tooltip.Group so moving between them switches at once.
DoPass the trigger’s own button through render instead of nesting a button inside Tooltip.Trigger.
DoAnimate the popup with data-starting-style and data-ending-style.
Don’tPut links or buttons in the popup. It cannot be reached by keyboard. Use Popover instead.
Don’tUse the tooltip as a button’s only name. Give the trigger its own aria-label; the tooltip only describes it.
Don’tPass 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.

PropTypeDescription
openbooleanWhether the tooltip is open, when controlled.
defaultOpenbooleanWhether the tooltip is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placementPlacementWhere the tooltip sits relative to the trigger.Default: 'top'
sideOffsetnumberGap to the trigger in px.Default: 4
delaynumberHover open delay in ms. Ignored inside a Tooltip.Group.Default: 200
closeDelaynumberHover close delay in ms. Ignored inside a Tooltip.Group.Default: 0

Tooltip.Group

Shares one delay across the tooltips inside it. Renders no element.

PropTypeDescription
delaynumber | { open?: number; close?: number }Open and close delay in ms. Replaces each member’s own.Default: { open: 200, close: 100 }
timeoutMsnumberHow 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.

PropTypeDescription
rootHTMLElement | 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

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