Usage
import { HoverCard } from "@voila.dev/ui/hover-card";<HoverCard.Root>
<HoverCard.Trigger render={<a href={profileUrl} />}>@nathan.guyot</HoverCard.Trigger>
<HoverCard.Content>
<ProviderPreview />
</HoverCard.Content>
</HoverCard.Root>A preview that appears when a pointer rests on a link — who a person is, what a project contains — without asking anyone to click. It opens on hover, which makes it the one overlay here that a touch user may never see, so nothing inside it may be the only route to an action or a fact. Treat it as enrichment. For help text use Tooltip; for content that survives a click, use Popover.
Recipes
Positioning works exactly as on Popover: side, align,
sideOffset, alignOffset and collisionPadding are direct props, and the
rest of the positioner is reachable through positionerProps.
Keep the card cheap to render — it may open on a pointer that was only passing through.
API
HoverCard.Root
| Prop | Type | Default | |
|---|---|---|---|
actionsRef | RefObject<PreviewCardRootActions | null> | — | A ref to imperative actions. |
children | PayloadChildRenderFunction<unknown> | ReactNode | — | The content of the preview card.
This can be a regular React node or a render function that receives the payload of the active trigger. |
defaultOpen | boolean | — | Whether the preview card is initially open. To render a controlled preview card, use the open prop instead. |
defaultTriggerId | string | null | — | ID of the trigger that the preview card is associated with.
This is useful in conjunction with the defaultOpen prop to create an initially open preview card. |
handle | PreviewCardHandle<unknown> | — | A handle to associate the preview card with a trigger. If specified, allows external triggers to control the card's open state. Can be created with the PreviewCard.createHandle() method. |
onOpenChange | ((open: boolean, eventDetails: PreviewCardRootChangeEventDetails) => void) | — | Event handler called when the preview card is opened or closed. |
onOpenChangeComplete | ((open: boolean) => void) | — | Event handler called after any animations complete when the preview card is opened or closed. |
open | boolean | — | Whether the preview card is currently open. |
triggerId | string | null | — | ID of the trigger that the preview card is associated with.
This is useful in conjunction with the open prop to create a controlled preview card.
There's no need to specify this prop when the preview card is uncontrolled (that is, when the open prop is not set). |
Plus the DOM props of the element it renders. Source: hover-card/components/hover-card-root.tsx.
HoverCard.Content
| Prop | Type | Default | |
|---|---|---|---|
positionerProps | Omit<PreviewCardPositionerProps, "align" | "alignOffset" | "children" | "collisionPadding" | "side" | "sideOffset"> | — | Escape hatch for the Positioner props not surfaced as dedicated ones —
sticky, anchor, positionMethod, arrowPadding. |
align | Align | "center" | How to align the popup relative to the specified side. |
alignOffset | number | OffsetFunction | 0 | Additional offset along the alignment axis in pixels.
Also accepts a function that returns the offset to read the dimensions of the anchor
and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: |
className | string | ((state: PreviewCardPopupState) => string | undefined) | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
collisionPadding | Padding | 8 | Additional space to maintain from the edge of the collision boundary. |
render | ComponentRenderFn<HTMLProps, PreviewCardPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> | — | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render. |
side | Side | "bottom" | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
sideOffset | number | OffsetFunction | 8 | Distance between the anchor and the popup in pixels.
Also accepts a function that returns the distance to read the dimensions of the anchor
and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: |
style | CSSProperties | ((state: PreviewCardPopupState) => CSSProperties | undefined) | — | Style applied to the element, or a function that returns a style object based on the component's state. |
Plus the DOM props of the element it renders. Source: hover-card/components/hover-card-content.tsx.
HoverCard.Trigger
| Prop | Type | Default | |
|---|---|---|---|
className | string | ((state: PreviewCardTriggerState) => string | undefined) | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
closeDelay | number | — | How long to wait before closing the preview card. Specified in milliseconds. |
delay | number | — | How long to wait before the preview card opens. Specified in milliseconds. |
handle | PreviewCardHandle<unknown> | — | A handle to associate the trigger with a preview card. |
payload | unknown | — | A payload to pass to the preview card when it is opened. |
render | ComponentRenderFn<HTMLProps, PreviewCardTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>> | — | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a ReactElement or a function that returns the element to render. |
style | CSSProperties | ((state: PreviewCardTriggerState) => CSSProperties | undefined) | — | Style applied to the element, or a function that returns a style object based on the component's state. |
Plus the DOM props of the element it renders. Source: hover-card/components/hover-card-trigger.tsx.
Related
Popover · Tooltip · UserAvatar