ts
| Guidance | Practices |
|---|---|
| Do | Use for rich content previews such as user profiles, entity summaries, and link previews. |
| Do | Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns. |
| Don't | Use for simple text hints: use Tooltip or useTooltip instead. |
| Param | Type | Description |
|---|---|---|
placement | 'above' | 'below' | 'start' | 'end' (default: 'above') | Position relative to the trigger. |
alignment | 'start' | 'center' | 'end' (default: 'center') | Alignment along the placement axis. |
delay | number (default: 300) | Delay before showing the hover card on hover, in milliseconds. |
hideDelay | number (default: 200) | Delay before hiding after mouse or focus leaves, in milliseconds. |
focusTrigger | 'auto' | 'always' | 'never' (default: 'auto') | When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements. |
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 hover card should be shown on mount. |
onShow | () => void | Callback fired when the hover card becomes visible. |
onHide | () => void | Callback fired when the hover card is hidden. |
| 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. Use when position and interaction live on different elements. |
| interactionRef | RefCallback<HTMLElement> | Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns. |
| anchorId | string | CSS anchor name for advanced positioning cases. |
| describedBy | string | ID to compose into aria-describedby on the trigger. |
| renderHoverCard | (children: ReactNode, props?: ContextRenderProps) => ReactNode | Render function for the anchor-positioned hover card content. |
| show | () => void | Imperatively show the hover card immediately. |
| hide | () => void | Imperatively hide the hover card immediately. |