Tooltip
An unstyled tooltip component with hover/focus triggers, delay management, and group transitions.
Build fully custom tooltips with complete control over layout and styling.
Pre-styled Versions
Features#
- Configurable
openDelayandcloseDelayfor timing control Managerenables instant transitions when hovering between adjacent tooltips- Interactive popup: hovering the tooltip content keeps it open by default, for pointer users only
- Arrow element with automatic per-side positioning via CSS custom properties
Usage#
import { Tooltip } from 'primereact/tooltip';<Tooltip.Manager>
<Tooltip.Root>
<Tooltip.Trigger></Tooltip.Trigger>
<Tooltip.Portal>
<Tooltip.Positioner>
<Tooltip.Popup>
<Tooltip.Arrow />
</Tooltip.Popup>
</Tooltip.Positioner>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Manager>Behavior#
Polymorphic Rendering#
Use as on any sub-component to change the rendered HTML element.
<Tooltip.Trigger as="div">...</Tooltip.Trigger>Render Function Children#
Sub-components accept a render function as children, providing access to the component instance.
<Tooltip.Trigger>{(instance) => <span>{instance.tooltip?.state.open ? 'Active' : 'Idle'}</span>}</Tooltip.Trigger>Pass Through#
The component's PT demo referenced as tooltip-pt is unavailable or does not exist.
API#
TooltipManager#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipManagerInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipManagerInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipManagerInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipManagerPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipManagerInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
openDelay | number | — |
| The delay in milliseconds before opening a tooltip. | ||
closeDelay | number | — |
| The delay in milliseconds before closing a tooltip. | ||
timeout | number | 400 |
| The timeout in milliseconds for the instant phase. If another tooltip opens within this timeout after a tooltip closes, the transition will be instant. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
Defines passthrough(pt) options of TooltipManager component.
| label | type | description |
|---|---|---|
| manager | TooltipManagerPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the manager's DOM element. |
TooltipRoot#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipRootInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipRootInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipRootInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipRootPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipRootInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
anchor | null | HTMLElement | undefined |
| External anchor element for positioning the tooltip programmatically. When provided, it is used instead of the element attached via `Tooltip.Trigger` . | ||
open | boolean | — |
| Controls the open state of the tooltip. | ||
defaultOpen | boolean | false |
| Whether the tooltip is open by default. | ||
onExitComplete | () => void | undefined |
| Callback fired after the leave (exit) transition completes. | ||
disabled | boolean | false |
| Whether the tooltip is disabled. | ||
openDelay | number | 600 |
| The delay in milliseconds before opening the tooltip on hover. | ||
closeDelay | number | 100 |
| The delay in milliseconds before closing the tooltip. | ||
interactive | boolean | true |
| Whether the tooltip popup is interactive (hoverable). When true, hovering over the popup keeps the tooltip open. When false, the tooltip closes as soon as the pointer leaves the trigger. This applies to pointer users only, content inside the popup is not reachable with the keyboard. | ||
onOpenChange | (event: TooltipRootChangeEvent) => void | undefined |
| Callback fired when the tooltip's open state changes. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-instant | Instant transition type when applicable |
Defines passthrough(pt) options of Tooltip component.
| label | type | description |
|---|---|---|
| root | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the root's DOM element. |
| trigger | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the trigger's DOM element. |
| portal | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the portal's DOM element. |
| positioner | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the positioner's DOM element. |
| popup | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the popup's DOM element. |
| arrow | TooltipRootPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the arrow's DOM element. |
TooltipTrigger#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipTriggerInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipTriggerInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipTriggerInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipTriggerPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipTriggerInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-popup-open | Present when tooltip is open |
Defines passthrough(pt) options of TooltipTrigger component.
| label | type | description |
|---|---|---|
| root | TooltipTriggerPassThroughType<HTMLAttributes<HTMLButtonElement>> | Used to pass attributes to the root's DOM element. |
TooltipPortal#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | (CSSProperties | ((instance?: PortalInstance | undefined) => CSSProperties | undefined)) & (CSSProperties | ((instance?: TooltipPortalInstance | undefined) => CSSProperties | undefined)) | — |
| The style to apply to the component. | ||
className | (string | ((instance?: PortalInstance | undefined) => string | undefined)) & (string | ((instance?: TooltipPortalInstance | undefined) => string | undefined)) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | BaseInstance<SafeRecord<PortalProps>, unknown, HTMLElement> & { props: SafeRecord<SafeRecord<PortalProps>>; attrs: Omit<SafeRecord<SafeRecord<PortalProps>>, string | number | symbol> & Record<PropertyKey, unknown> } & { state: SafeRecord; $computedSetup: SafeRecord } & PortalExposes & Record<PropertyKey, unknown> & useComponentPTReturnType & useComponentStyleReturnType & BaseInstance<SafeRecord<TooltipPortalProps>, unknown, HTMLElement> & { props: SafeRecord<SafeRecord<TooltipPortalProps>>; attrs: Omit<SafeRecord<SafeRecord<TooltipPortalProps>>, string | number | symbol> & Record<PropertyKey, unknown> } & { state: SafeRecord; $computedSetup: SafeRecord } & TooltipPortalExposes | — |
| The instance to pass to the component. | ||
pt | PortalPassThrough & Record<PropertyKey, unknown> & TooltipPortalPassThrough | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: PortalInstance) => ReactNode & (instance: TooltipPortalInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
onMounted | () => void | — |
| Callback function to invoke when the portal is mounted. | ||
onUnmounted | () => void | — |
| Callback function to invoke when the portal is unmounted. | ||
element | HTMLElement | ReactNode | — |
| The element to be rendered as the portal. | ||
elementRef | RefObject<null | HTMLElement> | — |
| The element reference to be rendered as the portal. | ||
appendTo | string | HTMLElement | ((instance: PortalInstance) => HTMLElement) | 'body' |
| The DOM element where the portal should be appended to. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
Defines passthrough(pt) options of TooltipPortal component.
| label | type | description |
|---|---|---|
| root | TooltipPortalPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the root's DOM element. |
TooltipPositioner#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipPositionerInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipPositionerInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipPositionerInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipPositionerPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipPositionerInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
align | AlignType | 'center' |
| The align of the positioner. | ||
sideOffset | number | — |
| The side offset of the positioner. | ||
alignOffset | number | 0 |
| The align offset of the positioner. | ||
flip | boolean | true |
| Whether to flip the positioner. | ||
shift | boolean | true |
| Whether to shift the positioner. | ||
hideWhenDetached | boolean | false |
| Whether to hide the positioner when detached. | ||
strategy | "fixed" | "absolute" | 'fixed' |
| The positioning strategy. | ||
boundary | HTMLElement | — |
| The boundary element that constrains the positioner placement. Used in JS fallback mode only; CSS Anchor mode uses the containing block. | ||
anchor | HTMLElement | — |
| The anchor element. | ||
content | HTMLDivElement | — |
| The content element. | ||
arrow | null | HTMLDivElement | — |
| The arrow element. | ||
autoZIndex | boolean | true |
| Whether to automatically manage layering. | ||
baseZIndex | number | 0 |
| Base zIndex value to use in layering. | ||
onPlacementChange | (placement: { side: SideType; align: AlignType }) => void | — |
| Callback invoked when the actual placement changes due to flip or shift. | ||
side | SideType | 'top' |
| The side of the positioner. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-open | Present when tooltip is open |
data-side | "top" | "bottom" | "left" | "right", placement |
data-align | "start" | "center" | "end", alignment |
CSS Custom Properties
The positioner element exposes CSS custom properties for layout and transform control.
| CSS Variable | Description |
|---|---|
--px-available-height | Available vertical space in pixels |
--px-available-width | Available horizontal space in pixels |
--px-transform-origin | Computed transform origin for animations |
--px-positioner-anchor-width | Width of the anchor/trigger element |
Defines passthrough(pt) options of TooltipPositioner component.
| label | type | description |
|---|---|---|
| root | TooltipPositionerPassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the root's DOM element. |
TooltipPopup#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipPopupInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipPopupInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipPopupInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipPopupPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipPopupInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
motionProps | UseMotionProps | — |
| Used to apply motion to the popup element. It accepts the same properties as the useMotion hook. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-open | Present when tooltip is visible |
data-instant | Present when an instant transition occurs |
data-instant-type | 'delay', 'focus', or 'dismiss' |
Defines passthrough(pt) options of TooltipPopup component.
| label | type | description |
|---|---|---|
| root | TooltipPopupPassThroughType<HTMLAttributes<HTMLButtonElement>> | Used to pass attributes to the root's DOM element. |
TooltipArrow#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: TooltipArrowInstance) => undefined | CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: TooltipArrowInstance) => undefined | string) | — |
| The class name to apply to the component. | ||
as | null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | TooltipArrowInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<TooltipArrowPassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: TooltipArrowInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-open | Present when tooltip is visible |
data-instant | Instant transition type when applicable |
data-side | "top" | "bottom" | "left" | "right", placement |
data-align | "start" | "center" | "end", alignment |
CSS Custom Properties
The arrow element exposes CSS custom properties for dynamic positioning:
| CSS Variable | Description |
|---|---|
--px-placer-arrow-x | Horizontal offset of arrow |
--px-placer-arrow-y | Vertical offset of arrow |
--px-placer-arrow-left | Left position of arrow element |
--px-placer-arrow-top | Top position of arrow element |
Defines passthrough(pt) options of TooltipArrow component.
| label | type | description |
|---|---|---|
| root | TooltipArrowPassThroughType<HTMLAttributes<HTMLButtonElement>> | Used to pass attributes to the root's DOM element. |
Accessibility#
Screen Reader#
Tooltip popup content should be descriptive and associated with a meaningful trigger label. The popup has role="tooltip", and while it is open the trigger's aria-describedby points to it.
Interactive Content#
Tooltip content is not reachable with the keyboard. The popup is portaled to the end of the document and closes when the trigger loses focus, so links or buttons inside it are only available to pointer users. Place interactive content in a Popover instead.
Keyboard Support#
| Key | Function |
|---|---|
tab | Focuses the trigger, opening the tooltip with instant transition. |
escape | Closes the open tooltip wherever focus is, without moving focus. Inside a dialog or popover, the first press closes only the tooltip. |