Hover Card

Reveal contextual preview content when a reader hovers over or focuses a link.

<HoverCard>
<HoverCardTrigger
  href="https://github.com/shadcn-ui"
  target="_blank"
  rel="noreferrer"
  className="inline-flex font-medium underline underline-offset-4"
>
  <span>@shadcn</span>
</HoverCardTrigger>
<HoverCardContent className="w-80 p-4">
  <div className="flex justify-between gap-4">
    <img
      src="https://github.com/shadcn-ui.png?size=96"
      alt="shadcn"
      width="48"
      height="48"
      className="size-12 rounded-full"
    />
    <div className="min-w-0 space-y-1.5">
      <p className="font-semibold text-popover-foreground">shadcn/ui</p>
      <p className="text-muted-foreground">
        Beautifully designed components that you can copy, own, and build on.
      </p>
      <div className="flex flex-wrap gap-x-3 gap-y-1 pt-1 text-[0.6875rem] text-muted-foreground">
        <span>127k GitHub stars</span>
        <span>Open source</span>
      </div>
    </div>
  </div>
</HoverCardContent>
</HoverCard>

HoverCard is a composable preview-card primitive for concise, contextual information. It consists of a root, an anchor-like trigger, and a floating content panel. The panel opens on hover and keyboard focus, so an inline documentation link can offer a useful preview without sending a reader away from the current page.

When to use it

Use a hover card for a short definition, author profile, repository summary, or contextual preview that helps a reader decide whether to follow a link. It works particularly well inside prose because the trigger renders as an anchor and supports keyboard focus as well as pointer hover.

Keep content brief and supplementary. A hover card is not a replacement for a required instruction, a form control, or a multi-step interaction: important content must remain available in the document itself. For a persistent disclosure, use Accordion; for a link to a related page, use RelatedTopic.

HoverCardContent is rendered in a portal, positioned relative to its trigger, and uses a 4-pixel gap by default. The trigger opens immediately in Heyo Docs (delay={0}), which is useful for quick documentation previews. Increase delay when a dense page would otherwise open cards too eagerly.

Position and timing

Positioned preview

Preview a release note

Rich content can turn an ordinary reference link into a helpful product preview. Keep the trigger useful on its own, then use the card for the detail that helps a reader decide whether to open it.

Version 2.4 release notes

<HoverCard defaultOpen>
<HoverCardTrigger
  className="font-medium underline underline-offset-4"
  href="/changelog"
>
  Version 2.4 release notes
</HoverCardTrigger>
<HoverCardContent align="start" className="w-72 p-4" sideOffset={8}>
  <div className="space-y-3">
    <Badge variant="secondary">New release</Badge>
    <div>
      <p className="font-semibold text-popover-foreground">Navigation presets</p>
      <p className="mt-1 text-sm text-muted-foreground">
        Start a new site with a useful structure, then customise it for your team.
      </p>
    </div>
    <Button href="/changelog" size="sm" variant="outline">
      Read the changelog
    </Button>
  </div>
</HoverCardContent>
</HoverCard>

Properties

defaultOpenbooleanoptional

A HoverCard prop that opens the card initially in uncontrolled mode. It defaults to false.

openbooleanoptional

A controlled HoverCard state. Supply this together with onOpenChange when another part of the page owns the open state.

onOpenChange(open, details) => voidoptional

Called whenever the root opens or closes. Use it to synchronise controlled state or record an interaction.

hrefstringoptional

An anchor attribute accepted by HoverCardTrigger. Give the trigger a real destination whenever possible so it remains a useful link without the preview.

delaynumberoptional

A HoverCardTrigger prop, in milliseconds, that delays opening. Heyo Docs defaults it to 0.

closeDelaynumberoptional

A HoverCardTrigger prop, in milliseconds, that delays closing after the pointer or focus leaves. The underlying primitive defaults to 300.

side"top" | "right" | "bottom" | "left"optional

A HoverCardContent prop that chooses the preferred side of the trigger. It defaults to bottom and may flip when the viewport does not have enough room.

align"start" | "center" | "end"optional

A HoverCardContent prop that aligns the panel along the selected side. It defaults to center.

sideOffsetnumberoptional

A HoverCardContent prop for the gap from the trigger. It defaults to 4 pixels.

alignOffsetnumberoptional

A HoverCardContent prop for fine-tuning alignment along the trigger. It defaults to 4 pixels.

classNamestringoptional

Extra classes accepted by the trigger and content components. Use it to style an inline trigger or change the panel's width and padding.