ts
| Guidance | Practices |
|---|---|
| Do | Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow. |
| Do | Provide a dashed underline on text triggers so users know the element is hoverable. |
| Do | Use the hook API (useXDSHoverCard) when you need more control over timing or placement. |
| Don't | Place critical actions or required information inside a hover card — users may miss content that only appears on hover. |
| Don't | Use a hover card when a simple Tooltip or Popover would suffice. |
| Don't | Use a HoverCard for content the user must interact with — it disappears when the cursor leaves. |
| Prop | Type | Description |
|---|---|---|
contentrequired | ReactNode | Hover card content. |
children | ReactNode | Trigger element that must accept a ref. |
placement | LayerPlacement (default: 'above') | Position relative to the anchor element. |
alignment | LayerAlignment (default: 'center') | Alignment along the placement axis. |
delay | number (default: 300) | Show delay in milliseconds. |
hideDelay | number (default: 200) | Hide delay in milliseconds. |
focusTrigger | 'auto' | 'always' | 'never' (default: 'auto') | Controls when focus events trigger the hover card. |
isEnabled | boolean (default: true) | Enables or disables the hover and focus triggers. |
onOpenChange | (isOpen: boolean) => void | Callback fired when hover card visibility changes. Called with true when shown and false when hidden. |
hasHoverIndication | 'auto' | boolean (default: 'auto') | Shows a dashed underline on the trigger element. |
isDefaultOpen | boolean | Whether the hover card should be shown on mount. Still dismissible. |