PreviewCard
A supplementary preview of a link on hover.
A supplementary preview of a link on hover.
Link preview#
Placement and delay#
Component parts#
| Component | Purpose |
|---|---|
PreviewCard | Root with open, defaultOpen, and onOpenChange |
PreviewCardTrigger | Link with href, delay, closeDelay, and render support |
PreviewCardContent | Styled popup with automatic portal and positioning |
Component props#
PreviewCard#
| Name | Type | Description |
|---|---|---|
| open | boolean | Controlled open state. |
| defaultOpen | boolean | Initial open state when uncontrolled (default: false). |
| onOpenChange | (open, eventDetails) => void | Called when the preview opens or closes. Event details include the reason and a cancel method. |
| onOpenChangeComplete | (open: boolean) => void | Called after the opening or closing animation completes. |
| triggerId | string | null | Identifies the active trigger when controlling the preview. |
| defaultTriggerId | string | null | Identifies the trigger for an initially open, uncontrolled preview. |
| actionsRef | RefObject | Receives imperative close and unmount actions. |
| handle | PreviewCardHandle | Associates the preview with detached triggers. |
| children | ReactNode | function | Preview parts, or a render function receiving the active trigger payload. |
The root does not render an HTML element. Set hover delays on PreviewCardTrigger and positioning options on PreviewCardContent.
PreviewCardTrigger#
| Name | Type | Description |
|---|---|---|
| href | string | Link destination. |
| delay | number | Delay in milliseconds before opening on hover (default: 600). |
| closeDelay | number | Delay in milliseconds before closing after the pointer leaves (default: 300). |
| id | string | Identifies this trigger for the root's triggerId or defaultTriggerId. |
| handle | PreviewCardHandle | Associates a detached trigger with a preview. |
| payload | Payload | Data passed to the root's children render function when this trigger is active. |
| children | ReactNode | Link content. |
| className | string | (state) => string | Additional link classes, optionally based on the open state. |
| style | CSSProperties | (state) => CSSProperties | Additional link styles. |
| render | ReactElement | function | Customizes the trigger element. |
Renders an anchor by default and supports standard anchor attributes and event handlers, including target and rel.
PreviewCardContent#
| Name | Type | Description |
|---|---|---|
| children | ReactNode | Content displayed inside the preview. |
| className | string | (state) => string | Additional popup classes, optionally based on popup state. |
| style | CSSProperties | (state) => CSSProperties | Popup styles, including width or height. |
| positionerProps | BasePreviewCard.Positioner.Props | Positioning options such as side, align, sideOffset, alignOffset, and collisionAvoidance. Zen defaults to side: 'bottom', align: 'start', and sideOffset: 8. |
| portalProps | BasePreviewCard.Portal.Props | Portal options, including a custom container and keepMounted (default: false). The portal is appended to document.body by default. |
| render | ReactElement | function | Customizes the popup element. |
BasePreviewCard refers to the PreviewCard namespace from @base-ui/react/preview-card. Positioning options belong inside positionerProps, and portal options belong inside portalProps.
The forwarded ref targets the popup div. Standard div attributes and event handlers are also supported. Styling callbacks receive the corresponding Base UI component state.
Preview content is supplementary: keep essential information accessible through the link destination. Use Popover for content that users must explicitly open and interact with.