Tooltip
A popup that appears when an element is hovered or focused, showing a hint for sighted users.
View as MarkdownUsage guidelines
- Prefer using tooltips as visual labels only: Tooltips should act as supplementary visual labels for sighted mouse and keyboard users. Tooltips alone are not accessible to touch or screen reader users. See Alternatives to tooltips for more details.
- Provide an accessible name for the trigger: Tooltips are visual-only elements and are not a replacement for labeling the trigger. The tooltip’s trigger must have an
aria-labelattribute that closely matches the tooltip’s content to ensure consistency for screen reader users.
Anatomy
Import the component and assemble its parts:
import { Tooltip } from '@base-ui/react/tooltip';
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Positioner>
<Tooltip.Popup>
<Tooltip.Arrow />
</Tooltip.Popup>
</Tooltip.Positioner>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>Alternatives to tooltips
Tooltips should be supplementary popups that provide non-essential clarity in high-density UIs. A user should not miss critical information if they never see a tooltip.
Tooltips don’t work well with touch input. Unlike mouse pointers with hover capability, there’s no easily discoverable way to reveal a tooltip before tapping its trigger on a touch device.
iOS doesn’t provide a system-standard, touch-friendly tooltip affordance, while Android may show a tooltip on long press. However, on the web, long press is often used to trigger contextual menus in the browser, which can lead to potential conflicts. For this reason, tooltips are disabled on touch devices.
Infotips
Popups that open when hovering an info icon should use Popover with the openOnHover prop on the trigger instead of a tooltip. This way, touch users and screen reader users can access the content.
To know when to reach for a popover instead of a tooltip, consider the purpose of the trigger element: If the trigger’s purpose is to open the popup itself, it’s a popover. If the trigger’s purpose is unrelated to opening the popup, it’s a tooltip.
Description text
Tooltips are designed for sighted users and are not a reliable way to deliver important information to touch users or assistive technologies. If the description is important to understanding the element, don’t hide it behind a tooltip — use inline text or Popover if space is limited, so the information is accessible to everyone.
Since tooltips serve sighted mouse and keyboard users, iconography should clearly communicate the purpose of icon-only triggers, especially on mobile where the text label may not be visible.
If the description is not critical, a tooltip can still be used to provide extra clarity for sighted mouse or keyboard users.
Contextual feedback messages
Use the Toast component’s anchoring ability for more ergonomic DX, to ensure the message is announced to screen readers, and to support complex content.
Examples
Detached triggers
A tooltip can be controlled by a trigger located either inside or outside the <Tooltip.Root> component.
For simple, one-off interactions, place the <Tooltip.Trigger> inside <Tooltip.Root>, as shown in the example at the top of this page.
However, if defining the tooltip’s content next to its trigger is not practical, you can use a detached trigger.
This involves placing the <Tooltip.Trigger> outside of <Tooltip.Root> and linking them with a handle created by the Tooltip.createHandle() function.
const demoTooltip = Tooltip.createHandle();
<Tooltip.Trigger handle={demoTooltip}>Button</Tooltip.Trigger>
<Tooltip.Root handle={demoTooltip}>
...
</Tooltip.Root>Multiple triggers
A single tooltip can be opened by multiple trigger elements.
You can achieve this by using the same handle for several detached triggers, or by placing multiple <Tooltip.Trigger> components inside a single <Tooltip.Root>.
<Tooltip.Root>
<Tooltip.Trigger>Trigger 1</Tooltip.Trigger>
<Tooltip.Trigger>Trigger 2</Tooltip.Trigger>
...
</Tooltip.Root>const demoTooltip = Tooltip.createHandle();
<Tooltip.Trigger handle={demoTooltip}>
Trigger 1
</Tooltip.Trigger>
<Tooltip.Trigger handle={demoTooltip}>
Trigger 2
</Tooltip.Trigger>
<Tooltip.Root handle={demoTooltip}>
...
</Tooltip.Root>The tooltip can render different content depending on which trigger opened it.
This is achieved by passing a payload to the <Tooltip.Trigger> and using the function-as-a-child pattern in <Tooltip.Root>.
The payload can be strongly typed by providing a type argument to the createHandle() function:
const demoTooltip = Tooltip.createHandle<{ text: string }>();
<Tooltip.Trigger handle={demoTooltip} payload={{ text: 'Trigger 1' }}>
Trigger 1
</Tooltip.Trigger>
<Tooltip.Trigger handle={demoTooltip} payload={{ text: 'Trigger 2' }}>
Trigger 2
</Tooltip.Trigger>
<Tooltip.Root handle={demoTooltip}>
{({ payload }) => (
<Tooltip.Portal>
<Tooltip.Positioner sideOffset={8}>
<Tooltip.Popup className={styles.Popup}>
<Tooltip.Arrow className={styles.Arrow}>
<ArrowSvg />
</Tooltip.Arrow>
{payload !== undefined && (
<span>
Tooltip opened by {payload.text}
</span>
)}
</Tooltip.Popup>
</Tooltip.Positioner>
</Tooltip.Portal>
)}
</Tooltip.Root>Controlled mode with multiple triggers
You can control the tooltip’s open state externally using the open and onOpenChange props on <Tooltip.Root>.
This allows you to manage the tooltip’s visibility based on your application’s state.
When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <Tooltip.Root> and the id prop on each <Tooltip.Trigger>.
Note that there is no separate onTriggerIdChange prop.
Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.
Animating the Tooltip
You can animate a tooltip as it moves between different trigger elements. This includes animating its position, size, and content.
Position and Size
To animate the tooltip’s position, apply CSS transitions to the left, right, top, and bottom properties of the Positioner part.
To animate its size, transition the width and height of the Popup part.
Content
The tooltip also supports content transitions. This is useful when different triggers display different content within the same tooltip.
To enable content animations, wrap the content in the <Tooltip.Viewport> part.
This part provides features to create direction-aware animations.
It renders a div with a data-activation-direction attribute (left, right, up, or down) that indicates the new trigger’s position relative to the previous one.
Inside the <Tooltip.Viewport>, the content is further wrapped in divs with data attributes to help with styling:
data-current: The currently visible content when no transitions are present or the incoming content.data-previous: The outgoing content during a transition.
You can use these attributes to style the enter and exit animations.
API reference
Provider
Provides a shared delay for multiple tooltips. The grouping logic ensures that once a tooltip becomes visible, the adjacent tooltips will be shown instantly.
delaynumber—
number- Name
- Description
How long to wait before opening a tooltip. Specified in milliseconds.
- Type
number | undefined
closeDelaynumber—
number- Name
- Description
How long to wait before closing a tooltip. Specified in milliseconds.
- Type
number | undefined
timeoutnumber400
number- Name
- Description
Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.
- Type
number | undefined- Default
400
childrenReact.ReactNode—
React.ReactNode- Name
- Type
React.ReactNode | undefined
Additional Types
Tooltip.Provider.Props
Re-Export of Provider props as TooltipProviderProps
Root
Groups all parts of the tooltip. Doesn’t render its own HTML element.
defaultOpenbooleanfalse
boolean- Name
- Description
Whether the tooltip is initially open.
To render a controlled tooltip, use the
openprop instead.- Type
boolean | undefined- Default
false
openboolean—
boolean- Name
- Description
Whether the tooltip is currently open.
- Type
boolean | undefined
onOpenChangefunction—
function- Name
- Description
Event handler called when the tooltip is opened or closed.
- Type
| (( open: boolean, eventDetails: Tooltip.Root.ChangeEventDetails, ) => void) | undefined
actionsRef| React.RefObject<Tooltip.Root.Actions
| null>—
| React.RefObject<Tooltip.Root.Actions
| null>- Name
- Description
A ref to imperative actions.
unmount: Unmounts the tooltip popup.close: Closes the tooltip imperatively when called.
- Type
React.RefObject<Tooltip.Root.Actions | null> | undefined
defaultTriggerIdstring | null—
string | null- Name
- Description
ID of the trigger that the tooltip is associated with. This is useful in conjunction with the
defaultOpenprop to create an initially open tooltip.- Type
string | null | undefined
handleTooltip.Handle<Payload>—
Tooltip.Handle<Payload>- Name
- Description
A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip’s open state. Can be created with the Tooltip.createHandle() method.
- Type
Tooltip.Handle<Payload> | undefined
onOpenChangeCompletefunction—
function- Description
Event handler called after any animations complete when the tooltip is opened or closed.
- Type
((open: boolean) => void) | undefined
triggerIdstring | null—
string | null- Name
- Description
ID of the trigger that the tooltip is associated with. This is useful in conjunction with the
openprop to create a controlled tooltip. There’s no need to specify this prop when the tooltip is uncontrolled (that is, when theopenprop is not set).- Type
string | null | undefined
trackCursorAxisUnion'none'
Union- Name
- Description
Determines which axis the tooltip should track the cursor on.
- Type
'none' | 'x' | 'y' | 'both' | undefined- Default
'none'
disabledbooleanfalse
boolean- Name
- Description
Whether the tooltip is disabled.
- Type
boolean | undefined- Default
false
disableHoverablePopupbooleanfalse
boolean- Description
Whether the tooltip contents can be hovered without closing the tooltip.
- Type
boolean | undefined- Default
false
children| React.ReactNode
| PayloadChildRenderFunction<Payload>—
| React.ReactNode
| PayloadChildRenderFunction<Payload>- Name
- Description
The content of the tooltip. This can be a regular React node or a render function that receives the
payloadof the active trigger.- Type
React.ReactNode | ((arg: { payload: unknown | undefined }) => ReactNode)<Payload> | undefined
Additional Types
Tooltip.Root.Props
Re-Export of Root props as TooltipRootProps
Tooltip.Root.State
type TooltipRootState = {};Tooltip.Root.Actions
type TooltipRootActions = { unmount: () => void; close: () => void };Tooltip.Root.ChangeEventReason
type TooltipRootChangeEventReason =
| 'trigger-hover'
| 'trigger-focus'
| 'trigger-press'
| 'outside-press'
| 'escape-key'
| 'disabled'
| 'imperative-action'
| 'none';Tooltip.Root.ChangeEventDetails
type TooltipRootChangeEventDetails =
| {
reason: 'trigger-hover';
event: MouseEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'trigger-focus';
event: FocusEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'trigger-press';
event:
| MouseEvent
| PointerEvent
| TouchEvent
| KeyboardEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'outside-press';
event: MouseEvent | PointerEvent | TouchEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'escape-key';
event: KeyboardEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'disabled';
event: Event;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'imperative-action';
event: Event;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'none';
event: Event;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}Trigger
An element to attach the tooltip to.
Renders a <button> element.
handleTooltip.Handle<Payload>—
Tooltip.Handle<Payload>- Name
- Description
A handle to associate the trigger with a tooltip.
- Type
Tooltip.Handle<Payload> | undefined
payloadPayload—
Payload- Name
- Description
A payload to pass to the tooltip when it is opened.
- Type
Payload | undefined
delaynumber600
number- Name
- Description
How long to wait before opening the tooltip. Specified in milliseconds.
- Type
number | undefined- Default
600
closeDelaynumber0
number- Name
- Description
How long to wait before closing the tooltip. Specified in milliseconds.
- Type
number | undefined- Default
0
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | ((state: Tooltip.Trigger.State) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: Tooltip.Trigger.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: Tooltip.Trigger.State, ) => ReactElement) | undefined
data-popup-open
Additional Types
Tooltip.Trigger.Props
Re-Export of Trigger props as TooltipTriggerProps
Tooltip.Trigger.State
type TooltipTriggerState = { open: boolean };Portal
A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to <body>.
Renders a <div> element.
containerUnion—
Union- Name
- Description
A parent element to render the portal element into.
- Type
| HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | undefined
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | ((state: Tooltip.Portal.State) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: Tooltip.Portal.State, ) => React.CSSProperties | undefined) | undefined
keepMountedbooleanfalse
boolean- Name
- Description
Whether to keep the portal mounted in the DOM while the popup is hidden.
- Type
boolean | undefined- Default
false
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: Tooltip.Portal.State, ) => ReactElement) | undefined
Additional Types
Tooltip.Portal.Props
Re-Export of Portal props as TooltipPortalProps
Tooltip.Portal.State
type TooltipPortalState = {};Positioner
Positions the tooltip against the trigger.
Renders a <div> element.
disableAnchorTrackingbooleanfalse
boolean- Description
Whether to disable the popup from tracking any layout shift of its positioning anchor.
- Type
boolean | undefined- Default
false
alignAlign'center'
Align- Name
- Description
How to align the popup relative to the specified side.
- Type
'start' | 'center' | 'end' | undefined- Default
'center'
alignOffsetnumber | OffsetFunction0
number | OffsetFunction- Name
- Description
Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a
dataobject parameter with the following properties:data.anchor: the dimensions of the anchor element with propertieswidthandheight.data.positioner: the dimensions of the positioner element with propertieswidthandheight.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
- Type
| number | ((data: { side: | 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'; align: 'start' | 'center' | 'end'; anchor: { width: number; height: number }; positioner: { width: number; height: number }; }) => number) | undefined- Default
0- Example
<Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} />
sideSide'top'
Side- Name
- Description
Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
- Type
| 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | undefined- Default
'top'
sideOffsetnumber | OffsetFunction0
number | OffsetFunction- Name
- Description
Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a
dataobject parameter with the following properties:data.anchor: the dimensions of the anchor element with propertieswidthandheight.data.positioner: the dimensions of the positioner element with propertieswidthandheight.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
- Type
| number | ((data: { side: | 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'; align: 'start' | 'center' | 'end'; anchor: { width: number; height: number }; positioner: { width: number; height: number }; }) => number) | undefined- Default
0- Example
<Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} />
arrowPaddingnumber5
number- Name
- Description
Minimum distance to maintain between the arrow and the edges of the popup.
Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
- Type
number | undefined- Default
5
anchorUnion—
Union- Name
- Description
An element to position the popup against. By default, the popup will be positioned against the trigger.
- Type
| Element | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null | undefined
collisionAvoidanceCollisionAvoidance—
CollisionAvoidance- Description
Determines how to handle collisions when positioning the popup.
- Type
CollisionAvoidance | undefined- Example
<Positioner collisionAvoidance={{ side: 'shift', align: 'shift', fallbackAxisSide: 'none', }} />
collisionBoundaryBoundary'clipping-ancestors'
Boundary- Description
An element or a rectangle that delimits the area that the popup is confined to.
- Type
Boundary | undefined- Default
'clipping-ancestors'
collisionPaddingPadding5
Padding- Name
- Description
Additional space to maintain from the edge of the collision boundary.
- Type
Padding | undefined- Default
5
stickybooleanfalse
boolean- Name
- Description
Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
- Type
boolean | undefined- Default
false
positionMethod'absolute' | 'fixed''absolute'
'absolute' | 'fixed'- Name
- Description
Determines which CSS
positionproperty to use.- Type
'absolute' | 'fixed' | undefined- Default
'absolute'
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | (( state: Tooltip.Positioner.State, ) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: Tooltip.Positioner.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: Tooltip.Positioner.State, ) => ReactElement) | undefined
data-open
data-closed
data-anchor-hidden
data-align
data-side
--anchor-height
The anchor’s height.
--anchor-width
The anchor’s width.
--available-height
The available height between the trigger and the edge of the viewport.
--available-width
The available width between the trigger and the edge of the viewport.
--transform-origin
The coordinates that this element is anchored to. Used for animations and transitions.
Additional Types
Tooltip.Positioner.Props
Re-Export of Positioner props as TooltipPositionerProps
Tooltip.Positioner.State
type TooltipPositionerState = {
open: boolean;
side:
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'inline-end'
| 'inline-start';
align: 'start' | 'center' | 'end';
anchorHidden: boolean;
instant: string | undefined;
}Popup
A container for the tooltip contents.
Renders a <div> element.
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | ((state: Tooltip.Popup.State) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: Tooltip.Popup.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: Tooltip.Popup.State, ) => ReactElement) | undefined
data-open
data-closed
data-align
data-instant
data-side
data-starting-style
data-ending-style
Additional Types
Tooltip.Popup.Props
Re-Export of Popup props as TooltipPopupProps
Tooltip.Popup.State
type TooltipPopupState = {
open: boolean;
side:
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'inline-end'
| 'inline-start';
align: 'start' | 'center' | 'end';
instant: 'delay' | 'focus' | 'dismiss' | undefined;
transitionStatus: TransitionStatus;
}Arrow
Displays an element positioned against the tooltip anchor.
Renders a <div> element.
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | ((state: Tooltip.Arrow.State) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: Tooltip.Arrow.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: Tooltip.Arrow.State, ) => ReactElement) | undefined
data-open
data-closed
data-uncentered
data-align
data-instant
data-side
Additional Types
Tooltip.Arrow.Props
Re-Export of Arrow props as TooltipArrowProps
Tooltip.Arrow.State
type TooltipArrowState = {
open: boolean;
side:
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'inline-end'
| 'inline-start';
align: 'start' | 'center' | 'end';
uncentered: boolean;
instant: 'delay' | 'dismiss' | 'focus' | undefined;
}createHandle
Creates a new handle to connect a Tooltip.Root with detached Tooltip.Trigger components.
Return value
Tooltip.Handle<Payload>Handle
A handle to control a tooltip imperatively and to associate detached triggers with it.
Properties
isOpenbooleanreadonly
boolean- Name
- Description
Indicates whether the tooltip is currently open.
- Type
boolean- Modifiers
readonly
Methods
open(triggerId)void
- Name
- Description
Opens the tooltip and associates it with the trigger with the given ID. The trigger must be a Tooltip.Trigger component with this handle passed as a prop.
This method should only be called in an event handler or an effect (not during rendering).
- Parameters
triggerId—stringID of the trigger to associate with the tooltip.
- Returns
void
close()void
- Name
- Description
Closes the tooltip.
- Returns
void