useTooltip
Hook that manages tooltip open state, hover/focus triggers, delay timing, and group transitions.
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, state, setRendered } = useTooltip({ tooltipManager: manager });
usePositioner({
anchor: state.anchorElement,
content: state.positionerElement,
arrow: state.arrowElement,
side: 'top',
sideOffset: 8,
flip: true
});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#
- Hover/focus open, opens on pointer enter or keyboard focus, closes on leave/blur with configurable
openDelayandcloseDelay - Presence tracking,
state.renderedturnstruewhen the tooltip opens and staystrueuntil you callsetRendered(false), so the popup can stay mounted through an exit animation - Interactive hover, allows the pointer to enter the popup without dismissing, configurable via the
interactiveprop; this is for pointer users only, popup content is not reachable with the keyboard - Group coordination,
useTooltipManagerskips the open delay when moving between adjacent tooltips for an "instant" transition - Transition awareness,
state.instantTypereports the current mode ('delay','focus','dismiss', orundefined) for styling - Ref callbacks,
triggerProps,positionerProps,popupProps, andarrowPropseach carry aref, so spreading them fillsstateandpopupRefwithout manual ref merging
Working with callbacks#
Controlled open state#
Pass open and onOpenChange to drive visibility from external state, useful when pairing with custom triggers or analytics.
const [isOpen, setIsOpen] = React.useState(false);
const { triggerProps, positionerProps, popupProps, arrowProps, state, setRendered } = useTooltip({
open: isOpen,
onOpenChange: (e) => setIsOpen(e.value)
});
React.useEffect(() => {
if (!state.open) setRendered(false);
}, [state.open]);
<>
<button {...triggerProps}></button>
{state.rendered &&
createPortal(
<div {...positionerProps}>
<div {...popupProps}>
<div {...arrowProps} />
</div>
</div>,
document.body
)}
</>;Tuning open and close delays#
Adjust openDelay and closeDelay to match the UI feel. Shorter delays feel snappier; longer delays avoid accidental opens.
const tooltip = useTooltip({ openDelay: 300, closeDelay: 200 });Group transitions with a manager#
Share a useTooltipManager instance so moving the pointer between siblings skips the open delay.
const manager = useTooltipManager({ timeout: 400 });
const tooltip1 = useTooltip({ tooltipManager: manager });
const tooltip2 = useTooltip({ tooltipManager: manager });Non-interactive tooltip#
Set interactive to false when the popup should dismiss immediately on pointer leave, even if the user moves over the tooltip content. interactive only controls pointer behavior, the popup is never part of the tab order, so links or buttons inside it belong in usePopover instead.
const tooltip = useTooltip({ interactive: false });Composing with usePositioner#
Pass the elements from state to usePositioner so the tooltip flips and offsets against the trigger.
const { state } = useTooltip();
usePositioner({
anchor: state.anchorElement,
content: state.positionerElement,
arrow: state.arrowElement,
side: 'top',
sideOffset: 8,
flip: true
});Styling with data attributes#
The hook exposes state through data-* attributes on each part. Use them as CSS selectors, no className juggling.
| Scope | Part | States |
|---|---|---|
tooltip | trigger | data-popup-open |
tooltip | popup | data-open, data-instant |
[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 |
|---|---|---|
useTooltipManager#
Accessibility#
Focus or hover shows the tooltip, Escape hides it, and content is announced via aria-describedby. Popup content is not reachable with the keyboard, so it must not hold links or buttons. See Primitive for full WAI-ARIA compliance details.