Tooltip
A popup that appears when an element is hovered or focused, showing a hint for sighted users.
Usage 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:
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.
The imperative methods on the handle, such as open() and close(), require a <Tooltip.Root> using the same handle to be mounted.
Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.
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>.
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 children snippet of <Tooltip.Root>, which receives the payload.
The payload can be strongly typed by providing a type argument to the createHandle() function:
Controlled mode with multiple triggers
You can control the tooltip's open state externally by binding the open prop 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 by binding the triggerId prop on <Tooltip.Root> and setting the id prop on each <Tooltip.Trigger>.
Note that there is no separate onTriggerIdChange prop. bind:triggerId follows the trigger that opens or closes the tooltip.
The onOpenChange callback also 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 that indicates the new trigger's position relative to the previous one. The value is a space-separated set of up to two tokens (one per axis) — left or right for the horizontal axis and up or down for the vertical axis (for example, right down). Match a single token with the ~= attribute selector, such as [data-activation-direction~='right'].
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
Shares a delay between tooltips. Once one tooltip is visible, its neighbours open instantly. Does not render its own HTML element.
delay number —
- Name
- Description
How long to wait before opening a tooltip on hover, in milliseconds.
- Type
number
closeDelay number —
- Name
- Description
How long to wait before closing a tooltip, in milliseconds.
- Type
number
timeout number 400
- Name
- Description
Another tooltip opens instantly if the previous one closed within this time, in milliseconds.
- Type
number- Default
400
Root
Groups all parts of the tooltip. Does not render its own HTML element.
open boolean false
- Name
- Description
Whether the tooltip is open. Use
bind:opento share it with the parent. A value passed withoutbind:holds until the parent changes it.- Type
boolean- Default
false- Binding
bind:open
onOpenChange function —
- Name
- Description
Called before the open state changes. Call
eventDetails.cancel()to veto it.- Type
(open: boolean, details: TooltipChangeEventDetails) => void
onOpenChangeComplete function —
- Name
- Description
Called after the open or close transition finishes.
- Type
(open: boolean) => void
disableHoverablePopup boolean false
- Description
Whether the tooltip contents can be hovered without closing the tooltip.
- Type
boolean- Default
false
trackCursorAxis TrackCursorAxis 'none'
- Name
- Description
Which axis the tooltip follows the cursor on.
- Type
TrackCursorAxis- Default
'none'
disabled boolean false
- Name
- Description
Whether the tooltip is disabled.
- Type
boolean- Default
false
triggerId string | null —
- Name
- Description
Id of the trigger the tooltip belongs to. Use
bind:triggerIdto follow it. An id written by a trigger press resets tonullonce the popup unmounts.- Type
string | null- Binding
bind:triggerId
handle TooltipHandle<Payload> —
- Name
- Description
Associates detached triggers and imperative
openandclose.- Type
TooltipHandle<Payload>
children Snippet<[{ payload: Payload | undefined }]> —
- Name
- Type
Snippet<[{ payload: Payload | undefined }]>
Trigger
An element to attach the tooltip to. Renders a <button> element.
handle TooltipHandle<Payload> —
- Name
- Type
TooltipHandle<Payload>
payload Payload —
- Name
- Description
A payload passed to the tooltip when this trigger opens it.
- Type
Payload
id string | null —
- Name
- Type
string | null
delay number 600
- Name
- Description
How long to wait before opening the tooltip on hover, in milliseconds.
- Type
number- Default
600
closeOnClick boolean true
- Name
- Description
Whether the tooltip closes when this trigger is clicked.
- Type
boolean- Default
true
closeDelay number 0
- Name
- Description
How long to wait before closing the tooltip, in milliseconds.
- Type
number- Default
0
disabled boolean | null —
- Name
- Description
Whether this trigger does not open the tooltip. It does not set the
disabledattribute on the element. Defaults to the root'sdisabled.- Type
boolean | null
render Snippet<[props: TooltipTriggerHostProps, state: TooltipTriggerState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: TooltipTriggerHostProps, state: TooltipTriggerState, children: Snippet | undefined]>
open boolean
- Name
open- Description
Whether the tooltip is open and was opened by this trigger.
- Type
boolean
data-popup-open
data-trigger-disabled
disabled prop or by a parent <Tooltip.Root> component.Portal
A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>.
keepMounted boolean false
- Name
- Description
Keep the portal mounted while the popup is closed.
- Type
boolean- Default
false
container HTMLElement | ShadowRoot | null —
- Name
- Description
Element the portal is appended to.
undefineduses the parent portal ordocument.body.nullwaits and does not mount until an element or shadow root is set. There is no ref object.- Type
HTMLElement | ShadowRoot | null
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: TooltipPortalState, children: Snippet | undefined]> —
- Name
- Description
Replace the portal element. The snippet receives host props, an empty state, and the children snippet. Host props include the move attachment.
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: TooltipPortalState, children: Snippet | undefined]>
Positioner
Positions the tooltip against the trigger. Renders a <div> element.
anchor Anchor —
- Name
- Description
An element to position the popup against. Defaults to the trigger.
- Type
Anchor
positionMethod "absolute" | "fixed" 'absolute'
- Name
- Type
"absolute" | "fixed"- Default
'absolute'
side Side 'top'
- Name
- Description
Which side of the anchor to place the popup on. May change to avoid collisions.
- Type
Side- Default
'top'
align Align 'center'
- Name
- Type
Align- Default
'center'
sideOffset number | OffsetFunction 0
- Name
- Type
number | OffsetFunction- Default
0
alignOffset number | OffsetFunction 0
- Name
- Type
number | OffsetFunction- Default
0
collisionBoundary Boundary 'clipping-ancestors'
- Name
- Type
Boundary- Default
'clipping-ancestors'
collisionPadding Padding 5
- Name
- Type
Padding- Default
5
arrowPadding number 5
- Name
- Type
number- Default
5
sticky boolean false
- Name
- Type
boolean- Default
false
disableAnchorTracking boolean false
- Type
boolean- Default
false
collisionAvoidance CollisionAvoidance —
- Name
- Type
CollisionAvoidance
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipPositionerState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipPositionerState, children: Snippet | undefined]>
open boolean
- Name
open- Type
boolean
side Side
- Name
side- Type
Side
align Align
- Name
align- Type
Align
anchorHidden boolean
- Name
anchorHidden- Type
boolean
instant TooltipInstant | 'tracking-cursor' | undefined
- Name
instant- Description
'tracking-cursor'while the tooltip follows the cursor.- Type
TooltipInstant | 'tracking-cursor' | undefined
data-open
data-closed
data-anchor-hidden
data-align
data-side
--anchor-height
--anchor-width
--available-height
--available-width
--positioner-height
height to this value when using CSS to animate size changes.--positioner-width
width to this value when using CSS to animate size changes.--transform-origin
Popup
A container for the tooltip contents. Renders a <div> element.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipPopupState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipPopupState, children: Snippet | undefined]>
open boolean
- Name
open- Type
boolean
side Side
- Name
side- Type
Side
align Align
- Name
align- Type
Align
instant TooltipInstant | undefined
- Name
instant- Type
TooltipInstant | undefined
transitionStatus 'starting' | 'ending' | 'idle' | undefined
- Name
transitionStatus- Type
'starting' | 'ending' | 'idle' | undefined
data-open
data-closed
data-align
data-instant
data-side
data-starting-style
data-ending-style
Arrow
Displays an element positioned against the tooltip anchor. Renders a <div> element.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipArrowState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipArrowState, children: Snippet | undefined]>
open boolean
- Name
open- Type
boolean
side Side
- Name
side- Type
Side
align Align
- Name
align- Type
Align
uncentered boolean
- Name
uncentered- Type
boolean
instant TooltipInstant | undefined
- Name
instant- Type
TooltipInstant | undefined
data-open
data-closed
data-uncentered
data-align
data-instant
data-side
Viewport
A viewport for displaying content transitions. Renders a <div> element. Only needed when one tooltip has several triggers, its content follows the trigger, and switching between them is animated.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipViewportState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: TooltipViewportState, children: Snippet | undefined]>
activationDirection string | undefined
- Name
activationDirection- Description
The direction from the previous trigger to the new one, as a horizontal and a vertical value separated by a space. Either value is empty when that axis did not move.
- Type
string | undefined
transitioning boolean
- Name
transitioning- Type
boolean
instant TooltipInstant | undefined
- Name
instant- Type
TooltipInstant | undefined
The Viewport is optional — reach for it only when a single popup is opened by multiple triggers, its content differs per trigger, and the switch between them is animated. When used, set width: var(--positioner-width) and height: var(--positioner-height) on the Positioner so its box is frozen to the measured size during the transition; otherwise content-driven resizing can make the popup thrash or flip to another side.
data-activation-direction
data-current
data-instant
data-previous
data-transitioning
--popup-height
--popup-width
createHandle
Creates a new handle to connect a Tooltip.Root with detached Tooltip.Trigger components.
Handle
Controls a Tooltip imperatively and associates detached Tooltip.Trigger components with a Tooltip.Root. Create one with Tooltip.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.
The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.
| Property | Type | Modifiers | Description |
|---|---|---|---|
isOpen | boolean | readonly | Whether the tooltip is currently open. Returns false while no root is attached to the handle. |
payload | Payload \| undefined | readonly | The payload of the trigger that opened the tooltip. |
Opens the tooltip and associates it with the trigger with the given id. It throws when no trigger with that id is registered, because the tooltip needs a trigger to anchor to.
This method should only be called in an event handler or an effect (not during rendering).
Closes the tooltip.
This method should only be called in an event handler or an effect (not during rendering).
Ends the closing phase of the tooltip immediately.