useTooltip

Hook that manages tooltip open state, hover/focus triggers, delay timing, and group transitions.

basic-demo

Usage#

import { usePositioner } from '@primereact/headless/positioner';
import { useTooltip } from '@primereact/headless/tooltip';
import { useTooltipManager } from '@primereact/headless/tooltipmanager';
import { createPortal } from 'react-dom';
 
const manager = useTooltipManager();
const { triggerProps, popupProps, arrowProps, positionerProps, setAnchorRef, setPositionerRef, setArrowRef, state, presence } = useTooltip({ tooltipManager: manager });
 
usePositioner({
    anchor: state.anchorElement,
    content: state.positionerElement,
    arrow: state.arrowElement,
    side: 'top',
    sideOffset: 8,
    flip: true
});
 
return (
    <>
        <button {...triggerProps} ref={setAnchorRef}></button>;
        {
            presence.present &&
                createPortal(
                    <div {...positionerProps} ref={setPositionerRef}>
                        <div {...popupProps} ref={presence.ref}>
                            <div {...arrowProps} ref={setArrowRef} />
                        </div>
                    </div>,
                    document.body
                );
        }
    </>
)

useTooltip manages hover/focus open behavior with configurable delays. Use useTooltipManager to coordinate instant transitions between adjacent tooltips in a group — see Primitive for a component-based API.

Features#

triggerProps, popupProps, arrowProps, and positionerProps return spread-ready props including data attributes
presence.present for conditional rendering with exit animation support
setAnchorRef, setPositionerRef, and setArrowRef callbacks for element registration
state.instantType tracks transition mode: 'delay', 'focus', 'dismiss', or undefined

Behavior#

Open Delay#

Set openDelay to control the delay before showing on hover. Defaults to 600.

const tooltip = useTooltip({ openDelay: 300 });

Close Delay#

Set closeDelay to control the delay before hiding on pointer leave. Defaults to 100.

const tooltip = useTooltip({ closeDelay: 200 });

Interactive#

Set interactive to false to close the tooltip as soon as the pointer leaves the trigger, ignoring hover over the popup. Defaults to true.

const tooltip = useTooltip({ interactive: false });

Disabled#

Set disabled to prevent the tooltip from opening.

const tooltip = useTooltip({ disabled: true });

Manager Group Behavior#

Wrap multiple tooltips with useTooltipManager to enable instant transitions when moving between adjacent tooltips. Set timeout on the manager to control the instant phase duration.

const manager = useTooltipManager({ timeout: 400 });
const tooltip1 = useTooltip({ tooltipManager: manager });
const tooltip2 = useTooltip({ tooltipManager: manager });

Controlled#

Pass open and onOpenChange for controlled usage.

const [isOpen, setIsOpen] = React.useState(false);
 
const tooltip = useTooltip({
    open: isOpen,
    onOpenChange: (e) => setIsOpen(e.open)
});

Custom Styling with Data Attributes#

[data-scope='tooltip'][data-part='popup'][data-open] {
    opacity: 1;
    scale: 1;
}
[data-scope='tooltip'][data-part='popup'][data-instant] {
    transition-duration: 0s;
}
[data-scope='tooltip'][data-part='trigger'][data-popup-open] {
    background-color: light-dark(var(--p-surface-100), var(--p-surface-700));
}

API#

useTooltip#

Name	Type	Default
`open`	`boolean`	—
Controls the open state of the tooltip.
`defaultOpen`	`boolean`	`false`
Whether the tooltip is open by default.
`onOpenChange`	`(event: useTooltipChangeEvent) => void`	`undefined`
Callback fired when the open state changes.
`disabled`	`boolean`	`false`
Whether the tooltip is disabled.
`openDelay`	`number`	`600`
The delay in milliseconds before opening the tooltip on hover.
`closeDelay`	`number`	`0`
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.
`tooltipManager`	`useTooltipManagerExposes`	—
The tooltip manager instance for group behavior.

useTooltipManager#

Name	Type	Default
`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.

Accessibility#

See Tooltip Primitive for WAI-ARIA compliance details and keyboard support.