Tooltip for a short explanation of a control or truncated text. Keep essential information visible, give controls an accessible name, and use Popover when the content contains links, buttons, or other controls.
Single trigger
children. Native elements receive the trigger attributes, event handlers, and ref directly. Custom trigger components must forward all of them. A wrapper element also works with a component that does not forward every trigger prop.
Hover opens the tooltip after delay milliseconds, which defaults to 600. Keyboard focus opens it immediately. closeDelay defaults to 0; hovering over the popup keeps it open unless disableHoverablePopup is set. Escape dismisses it.
Controlled state
Useopen and onOpenChange together when the application owns visibility. Use defaultOpen only to set the initial visibility of an uncontrolled tooltip.
Rich content and composition
Tooltip.Content provides a title, optional description, and optional leading icon. Use it as content or inside Tooltip.Popup.
Tooltip.createHandle() connects detached triggers to a shared Root through their handle prop. Keep each popup’s content supplementary even when several triggers share it.
Disabled controls
Native disabled buttons cannot receive keyboard focus. Wrap one in a focusable trigger so users can discover why the action is unavailable.disabled on Tooltip suppresses the tooltip itself. It does not disable the control.
Placement and overflowing text
The popup defaults toside="top", align="center", sideOffset={10}, and a maximum width of 300 pixels. Placement adjusts to available space. Use arrow for an arrow and container to override the theme’s portal destination; see theming.
Use OverflowingTextWithTooltip when a text label should show its full value only when truncated. Its existing text, tooltipContent, and tooltipPlace props remain available.
Props
The reference is generated from the public component types. Native popup attributes and event handlers are also accepted.RefObject<TooltipRootActions | null>
A ref to imperative actions.
unmount: Unmounts the tooltip popup.close: Closes the tooltip imperatively when called.
"center" | "end" | "start"
Alignment relative to the trigger. Defaults to center.
number | OffsetFunction
default:"0"
Offset along the alignment axis in pixels.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An explicit positioning anchor for the popup.
boolean
Displays an arrow pointing to the trigger. Defaults to false.
ReactElement<unknown, string | JSXElementConstructor<any>>
required
A single trigger element. Custom components must forward their ref, native attributes, and event handlers.
string | ((state: TooltipPopupState) => string | undefined)
Additional CSS class for the popup.
number
default:"0"
Delay in milliseconds before closing after hover ends. Defaults to 0.
boolean
default:"true"
Whether the tooltip should close when this trigger is clicked.
CollisionAvoidance
Determines how to handle collisions when positioning the popup.
side controls overflow on the preferred placement axis (top/bottom or left/right):'flip': keep the requested side when it fits; otherwise try the opposite side (topandbottom, orleftandright).'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.'none': do not correct side-axis overflow.
align controls overflow on the alignment axis (start/center/end):'flip': keep side, but swapstartandendwhen the requested alignment overflows.'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.'none': do not correct alignment-axis overflow.
fallbackAxisSide controls fallback behavior on the perpendicular axis when the
preferred axis cannot fit:'start': allow perpendicular fallback and try the logical start side first (topbeforebottom, orleftbeforerightin LTR).'end': allow perpendicular fallback and try the logical end side first (bottombeforetop, orrightbeforeleftin LTR).'none': do not fallback to the perpendicular axis.
side is 'shift', explicitly setting align only supports 'shift' or 'none'.
If align is omitted, it defaults to 'flip'.Boundary
default:"clipping-ancestors"
An element or a rectangle that delimits the area that the popup is confined to.
Padding
default:"5"
Additional space to maintain from the edge of the collision boundary.
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
Portal destination. Defaults to the current theme container.
ReactNode
required
Supplementary content displayed in the tooltip.
boolean
default:"false"
Initial visibility when the tooltip manages its own state.
string | null
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the
defaultOpen prop to create an initially open tooltip.number
default:"600"
Delay in milliseconds before opening on hover. Defaults to 600.
boolean
default:"false"
Whether to disable the popup from tracking any layout shift of its positioning anchor.
boolean
default:"false"
Prevents the tooltip from opening.
boolean
default:"false"
Prevents hovering over the popup from keeping it open.
boolean
Keeps the popup mounted while closed.
MaxWidth<string | number>
Maximum popup width. Defaults to 300 pixels.
((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)
Called when an interaction requests a visibility change.
((open: boolean) => void)
Event handler called after any animations complete when the tooltip is opened or closed.
boolean
Controlled visibility of the tooltip.
"absolute" | "fixed"
default:"absolute"
CSS positioning method for the popup.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render."bottom" | "left" | "right" | "top"
Preferred side of the trigger. Defaults to top and may change to avoid collisions.
number | OffsetFunction
default:"10"
Distance from the trigger in pixels. Defaults to 10.
boolean
default:"false"
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)
Inline styles for the popup.
"both" | "none" | "x" | "y"
default:"none"
Determines which axis the tooltip should track the cursor on.
string | null
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the
open prop to create a controlled tooltip.
There’s no need to specify this prop when the tooltip is uncontrolled (that is, when the open prop is not set).Tooltip.Root
RefObject<TooltipRootActions | null>
A ref to imperative actions.
unmount: Unmounts the tooltip popup.close: Closes the tooltip imperatively when called.
ReactNode | PayloadChildRenderFunction<Payload>
The content of the tooltip.
This can be a regular React node or a render function that receives the
payload of the active trigger.boolean
default:"false"
Whether the tooltip is initially open.To render a controlled tooltip, use the
open prop instead.string | null
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the
defaultOpen prop to create an initially open tooltip.boolean
default:"false"
Whether the tooltip is disabled.
boolean
default:"false"
Whether the tooltip contents can be hovered without closing the tooltip.
TooltipHandle<Payload>
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.
((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)
Event handler called when the tooltip is opened or closed.
((open: boolean) => void)
Event handler called after any animations complete when the tooltip is opened or closed.
boolean
Whether the tooltip is currently open.
"both" | "none" | "x" | "y"
default:"none"
Determines which axis the tooltip should track the cursor on.
string | null
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the
open prop to create a controlled tooltip.
There’s no need to specify this prop when the tooltip is uncontrolled (that is, when the open prop is not set).Tooltip.Trigger
string | ((state: TooltipTriggerState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
number
default:"0"
How long to wait before closing the tooltip. Specified in milliseconds.
boolean
default:"true"
Whether the tooltip should close when this trigger is clicked.
number
default:"600"
How long to wait before opening the tooltip on hover. Specified in milliseconds.
boolean
default:"false"
If
true, the tooltip will not open when interacting with this trigger.
Note that this doesn’t apply the disabled attribute to the trigger element.
If you want to disable the trigger element itself, you can pass the disabled prop to the trigger element via the render prop.TooltipHandle<Payload>
A handle to associate the trigger with a tooltip.
Payload
A payload to pass to the tooltip when it is opened.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.CSSProperties | ((state: TooltipTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Popup
"center" | "end" | "start"
default:"center"
Alignment relative to the trigger. Defaults to center.
number | OffsetFunction
default:"0"
Offset along the alignment axis in pixels.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An explicit positioning anchor for the popup.
boolean
default:"false"
Displays an arrow pointing to the trigger. Defaults to false.
string | ((state: TooltipPopupState) => string | undefined)
Additional CSS class for the popup.
CollisionAvoidance
Determines how to handle collisions when positioning the popup.
side controls overflow on the preferred placement axis (top/bottom or left/right):'flip': keep the requested side when it fits; otherwise try the opposite side (topandbottom, orleftandright).'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.'none': do not correct side-axis overflow.
align controls overflow on the alignment axis (start/center/end):'flip': keep side, but swapstartandendwhen the requested alignment overflows.'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.'none': do not correct alignment-axis overflow.
fallbackAxisSide controls fallback behavior on the perpendicular axis when the
preferred axis cannot fit:'start': allow perpendicular fallback and try the logical start side first (topbeforebottom, orleftbeforerightin LTR).'end': allow perpendicular fallback and try the logical end side first (bottombeforetop, orrightbeforeleftin LTR).'none': do not fallback to the perpendicular axis.
side is 'shift', explicitly setting align only supports 'shift' or 'none'.
If align is omitted, it defaults to 'flip'.Boundary
default:"clipping-ancestors"
An element or a rectangle that delimits the area that the popup is confined to.
Padding
default:"5"
Additional space to maintain from the edge of the collision boundary.
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
Portal destination. Defaults to the current theme container.
boolean
default:"false"
Whether to disable the popup from tracking any layout shift of its positioning anchor.
boolean
Keeps the popup mounted while closed.
MaxWidth<string | number>
default:"300px"
Maximum popup width. Defaults to 300 pixels.
"absolute" | "fixed"
default:"absolute"
CSS positioning method for the popup.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render."bottom" | "left" | "right" | "top"
default:"top"
Preferred side of the trigger. Defaults to top and may change to avoid collisions.
number | OffsetFunction
default:"10"
Distance from the trigger in pixels. Defaults to 10.
boolean
default:"false"
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)
Inline styles for the popup.
Tooltip.Content
ReactNode
Secondary explanation beneath the primary text.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.ReactNode
An icon displayed before the text.
Tooltip.Provider
number
How long to wait before closing a tooltip. Specified in milliseconds.
number
How long to wait before opening the tooltip on hover. Specified in milliseconds.
number
default:"400"
Another tooltip will open instantly if the previous tooltip
is closed within this timeout. Specified in milliseconds.