Tooltip | Base Design System

Tooltip names a control whose purpose is not obvious from its face — most often an icon-only button. It is supplementary: anything the reader must have cannot live here, because pointer users see it late and touch users never see it.

TooltipTrigger takes exactly two children: the control, then the tooltip.

Placement

Top

<TooltipTrigger delay={0}>
<Button variant="outline">Top</Button>
<Tooltip placement="top">Above the trigger</Tooltip>
</TooltipTrigger>

Right

<TooltipTrigger delay={0}>
<Button variant="outline">Right</Button>
<Tooltip placement="right">Beside the trigger</Tooltip>
</TooltipTrigger>

Bottom

<TooltipTrigger delay={0}>
<Button variant="outline">Bottom</Button>
<Tooltip placement="bottom">Below the trigger</Tooltip>
</TooltipTrigger>

placement defaults to top and flips automatically when there is no room, so treat it as a preference rather than a guarantee.

Delay

delay defaults to 1500ms — long enough that tooltips do not flicker as the pointer crosses a toolbar. Lower it only when the tooltip is the sole label for a control and the reader is likely to need it immediately.

closeDelay defaults to 0. Raise it when adjacent triggers should feel like one group rather than flashing between labels.

When to use

Use Tooltip to name a control whose purpose is not obvious from its face — most often an icon-only button.

Use something else when:

The reader must have the information. Put it on the page, like a Text Field description.
The content has links or controls. Use Popover.

Usage

Keep it to a few words naming the control. A tooltip is a label, not a paragraph.

Don't

Put required information, links, or interactive content inside. The tooltip dismisses on pointer-out and cannot be reached with a pointer or a screen reader's cursor.

Props

Prop	Type	Default
`arrowBoundaryOffset` The minimum distance the arrow's edge should be from the edge of the overlay element.	Type`number`	Default`0`
`className` The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the	Type`ClassNameOrFunction<TooltipRenderProps>`	Default—
`containerPadding` The placement padding that should be applied between the element and its	Type`number`	Default`12`
`crossOffset` The additional offset applied along the cross axis between the element and its	Type`number`	Default`0`
`defaultOpen` Whether the overlay is open by default (uncontrolled).	Type`boolean`	Default—
`isEntering` Whether the tooltip is currently performing an entry animation.	Type`boolean`	Default—
`isExiting` Whether the tooltip is currently performing an exit animation.	Type`boolean`	Default—
`isOpen` Whether the element is rendered.	Type`boolean`	Default—
`offset` The additional offset applied along the main axis between the element and its	Type`number`	Default`8`
`placement` The placement of the tooltip with respect to the trigger.	Type`enum`	Default`'top'`
`shouldFlip` Whether the element should flip its orientation (e.g. top to bottom or left to right) when	Type`boolean`	Default`true`
`triggerRef` The ref for the element which the tooltip positions itself with respect to.	Type`RefObject<Element \| null>`	Default—
`UNSTABLE_portalContainer` The container element in which the overlay portal will be placed. This may have unknown	Type`Element`	Default`document.body`

TooltipTrigger

Prop	Type	Default
`closeDelay` The delay time for the tooltip to close. [See	Type`number`	Default`0`
`defaultOpen` Whether the overlay is open by default (uncontrolled).	Type`boolean`	Default—
`delay` The delay time for the tooltip to show up. [See	Type`number`	Default`1500`
`isDisabled` Whether the tooltip should be disabled, independent from the trigger.	Type`boolean`	Default—
`isOpen` Whether the overlay is open by default (controlled).	Type`boolean`	Default—
`shouldCloseOnPress` Whether the tooltip should close when the trigger is pressed.	Type`boolean`	Default`true`
`trigger` By default, opens for both focus and hover. Can be made to open only for focus.	Type`"hover" \| "focus"`	Default`'hover'`

Accessibility

Tooltip wraps React Aria's Tooltip, which shows on keyboard focus as well as hover and dismisses on Escape. It does not replace an accessible name: an icon-only button still needs aria-label, because the tooltip is described content, not the button's label.

The tooltip grows from its trigger and leaves with a shorter, smaller fade. When the reader prefers reduced motion, it appears and disappears without animating.