Usage
Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.ts
Best practices
| 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. |
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
placement | 'below' | 'above' | 'end' | 'start' | 'above' | Position relative to the trigger. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS). |
alignment | 'end' | 'start' | 'center' | 'center' | Alignment along the placement axis. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS). |
delay | number | 300 | Delay before showing the hover card on hover, in milliseconds. |
hideDelay | number | 200 | Delay before hiding after mouse or focus leaves, in milliseconds. |
focusTrigger | 'auto' | 'always' | 'never' | 'auto' | When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements. |
isEnabled | boolean | true | Whether hover and focus triggers are enabled. |
label | string | — | Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed). |
isOpen | boolean | — | Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility. |
isDefaultOpen | boolean | 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. |
Returns
| Field | Type | Default | Description |
|---|---|---|---|
ref | (node: HTMLElement | null) => void | — | Combined ref that sets both position and interaction on the same trigger element. Svelte has no ref prop. Reach the element with an attachment through the spread props; |
positionRef | (node: HTMLElement | null) => void | — | Ref for the positioning anchor element. Use when position and interaction live on different elements. Element references are attachments here. The port returns an |
interactionRef | (node: HTMLElement | null) => void | — | Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns. Element references are attachments here. The port returns an |
anchorId | string | — | CSS anchor name for advanced positioning cases. |
describedBy | string | — | ID to compose into aria-describedby on the trigger. |
renderHoverCard | (children: string | Snippet, props?: Omit<ContextRenderProps, 'positioning'>) => string | Snippet | — | Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment. A Svelte hook cannot return markup. This hook returns state only; render its companion component and pass the hook’s value to it.Upstream declares |
show | () => void | — | Imperatively show the hover card immediately. |
hide | () => void | — | Imperatively hide the hover card immediately. |