Hover Card

Reveal supporting information when a trigger is hovered or focused.

View component source ↗

Preview

Example

A minimal example to get started.

@yihyunjoon/ui

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/hover-card.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { HoverCard, HoverCardTrigger, HoverCardContent } from "@/components/ui/hover-card";

export default function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="/docs" className="underline underline-offset-4" />}>
        @yihyunjoon/ui
      </HoverCardTrigger>
      <HoverCardContent>
        <p className="font-semibold">Open source components</p>
        <p className="text-sm text-muted-foreground">A customizable registry built on Base UI.</p>
      </HoverCardContent>
    </HoverCard>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

HoverCard

HoverCard properties
Prop	Type	Default	Description
`defaultOpen`	boolean \| undefined boolean \| undefined	`false`	Whether the preview card is initially open. To render a controlled preview card, use the `open` prop instead.
`open`	boolean \| undefined boolean \| undefined	`—`	Whether the preview card is currently open.
`onOpenChange`	((open: boolean, eventDetails: PreviewCardPrimitive.Root.ChangeEventDetails) => void) \| un… ((open: boolean, eventDetails: PreviewCardPrimitive.Root.ChangeEventDetails) => void) \| undefined	`—`	Event handler called when the preview card is opened or closed.
`onOpenChangeComplete`	((open: boolean) => void) \| undefined ((open: boolean) => void) \| undefined	`—`	Event handler called after any animations complete when the preview card is opened or closed.
`actionsRef`	React.RefObject<PreviewCardRootActions \| null> \| undefined React.RefObject<PreviewCardRootActions \| null> \| undefined	`—`	A ref to imperative actions. - `unmount`: Unmounts the preview card popup. - `close`: Closes the preview card imperatively when called.
`handle`	PreviewCardPrimitive.Handle<unknown> \| undefined PreviewCardPrimitive.Handle<unknown> \| undefined	`—`	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.
`children`	React.ReactNode \| PayloadChildRenderFunction<unknown> React.ReactNode \| PayloadChildRenderFunction<unknown>	`—`	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.
`triggerId`	string \| null \| undefined string \| null \| undefined	`—`	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).
`defaultTriggerId`	string \| null \| undefined string \| null \| undefined	`—`	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.

HoverCardTrigger

HoverCardTrigger properties
Prop	Type	Default	Description
`handle`	PreviewCardPrimitive.Handle<unknown> \| undefined PreviewCardPrimitive.Handle<unknown> \| undefined	`—`	A handle to associate the trigger with a preview card.
`payload`	unknown unknown	`—`	A payload to pass to the preview card when it is opened.
`delay`	number \| undefined number \| undefined	`600`	How long to wait before the preview card opens. Specified in milliseconds.
`closeDelay`	number \| undefined number \| undefined	`300`	How long to wait before closing the preview card. Specified in milliseconds.
`ref`	React.Ref<HTMLAnchorElement> \| undefined React.Ref<HTMLAnchorElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLAnchorElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLAnchorElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLAnchorElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLAnchorElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLAnchorElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLAnchorElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLAnchorElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLAnchorElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLAnchorElement, MouseEvent>>) => void) \| undefine… ((event: BaseUIEvent<React.MouseEvent<HTMLAnchorElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`type`	string \| undefined string \| undefined	`—`	The native input or button behavior.
`target`	React.HTMLAttributeAnchorTarget \| undefined React.HTMLAttributeAnchorTarget \| undefined	`—`	Browsing context in which the link opens.
`href`	string \| undefined string \| undefined	`—`	Destination URL for the link.
`className`	string \| ((state: PreviewCardTriggerState) => string \| undefined) \| undefined string \| ((state: PreviewCardTriggerState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PreviewCardTriggerState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PreviewCardTriggerState) => React.CSSProperties \| undefined… React.CSSProperties \| ((state: PreviewCardTriggerState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

HoverCardContent

HoverCardContent properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: PreviewCardPopupState) => string \| undefined) \| undefined string \| ((state: PreviewCardPopupState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PreviewCardPopupState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PreviewCardPopupState) => React.CSSProperties \| undefined) … React.CSSProperties \| ((state: PreviewCardPopupState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`align`	Align \| undefined Align \| undefined	`"center"`	How to align the popup relative to the specified side.
`side`	Side \| undefined Side \| undefined	`"bottom"`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`sideOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`4`	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: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
`alignOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`4`	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: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.

Usage notes

Use it for optional context rather than essential instructions. Keep the trigger useful as a link even without opening the card.