Skip to the content

Tooltip

Tooltip is a short hint anchored to an element. It opens when the pointer rests on the anchor or the anchor receives keyboard focus, and closes on leave, blur, Escape or an outside press. For a title plus a description, use Popover.
Overlays

When to use

Use when
  • An icon or button needs a name or a clarification.
  • A menu item shows its keyboard shortcut.
Avoid when
  • The information is critical — a hint that needs hover or focus is easy to miss, especially on touch screens.
  • The content is long or structured — use Popover.
  • You report the result of an action — use Notification.

Usage

<Tooltip content="Like this post">
  <Button size="small" text="Hover or focus me" />
</Tooltip>

content and children accept a string or a node. The child must forward its ref to a DOM element — the bubble positions against it. In uncontrolled mode the tooltip takes over the child's onFocus, onBlur, onPointerEnter and onPointerLeave handlers.

Variants

position takes the 12 placements below (default top); the bubble flips and shifts to stay in view.

loading

Controlled mode: pass visible and onDismiss together — the component throws without onDismiss. In this mode hover and focus do nothing; Escape and an outside press call onDismiss.

const { active, toggle, disable } = useToggle();

<Tooltip visible={active} onDismiss={disable} position="right" content="Shown on click">
  <Button onClick={toggle} size="small" text="Toggle hint" />
</Tooltip>;

inverted switches to the raised surface for dark backgrounds; noArrow hides the arrow. The bubble scales in from the anchor side and fades out (motion="scale"); pass another motion preset or motion="none". interactive is deprecated and has no effect.

Stacking

The bubble paints above every open layer. Inside a Modal or Sheet it renders inside that overlay. Anywhere else it portals to document.body on theme.zIndex.tooltip (default 10000). That tier sits above modal (9999), toast (1000), dropdown (500) and sticky (10). When a theme raises modal, keep tooltip above it:

createTheme({ zIndex: { modal: 20000, tooltip: 20001 } });

Accessibility

  • The bubble has role="tooltip"; while it is open the anchor gets aria-describedby pointing at it.
  • Keyboard users open it by focusing the anchor and close it with Escape. Use a focusable anchor.
  • A tooltip describes; it does not name. An icon-only button still needs its own aria-label.

Properties

See also