Usage
Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.
ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls. |
| Do | Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child. |
| Do | For a toggle-style trigger, have your own button call show() and hide() on each press. Give it aria-describedby and aria-controls set to describedBy, and aria-expanded (true while show() holds the tooltip, false after hide() or onHide), and keep its own accessible name. For an info icon, use InfoTip instead. |
| Don't | Put interactive content inside tooltips: use Popover or HoverCard instead. |
Parameters
| Param | Type | Description |
|---|---|---|
placement | 'above' | 'below' | 'start' | 'end' (default: 'above') | Position relative to the trigger. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS). |
alignment | 'start' | 'center' | 'end' (default: 'center') | Alignment along the placement axis. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS). |
delay | number (default: 200) | Delay before showing on hover, in milliseconds. |
hideDelay | number (default: 0) | Delay before hiding after mouse or focus leaves, in milliseconds. |
focusTrigger | 'auto' | 'always' | 'never' (default: 'auto') | When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it. |
touchTrigger | 'auto' | 'tap' | 'none' (default: 'auto') | What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (a button whose only job is revealing the tooltip); none never opens on touch. |
isEnabled | boolean (default: true) | Whether hover and focus triggers are enabled. |
isOpen | boolean | Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility. |
isDefaultOpen | boolean (default: false) | Whether the tooltip should be shown on mount. |
onShow | () => void | Callback fired when the tooltip becomes visible. |
onHide | () => void | Callback fired when the tooltip is hidden. |
Returns
| Field | Type | Description |
|---|---|---|
| ref | RefCallback<HTMLElement> | Combined ref that sets both position and interaction on the same trigger element. |
| positionRef | RefCallback<HTMLElement> | Ref for the positioning anchor element. |
| interactionRef | RefCallback<HTMLElement> | Ref for the hover/focus interaction element. |
| anchorId | string | CSS anchor name for advanced positioning cases. |
| describedBy | string | ID to compose into aria-describedby on the trigger. |
| renderTooltip | (children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode | Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment. |
| show | () => void | Opens the tooltip now and keeps it open until hide(), Escape, a press outside, or focus leaving its trigger. Its text is announced once, and onShow fires. Under a controlled isOpen it only calls onShow. Does nothing while isEnabled is false. |
| hide | () => void | Closes the tooltip now, and onHide fires. Under a controlled isOpen it only calls onHide. |
Examples
Common configurations, variations, and states.Use with shadcn
Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.
This install URL expires with the draft preview.bash