Skip to content
WunderUI

Hover Card

Free

A card that previews what a link points to when the pointer rests on it or the keyboard focuses it.

npx wunderui-cli add hover-card

Playground

Installation

bash
npx wunderui-cli add hover-card

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

Then use it:

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

export function ProfileLink() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="/team/nora-lindgren" />} className="font-medium text-text-link underline-offset-4 hover:underline">
        @noralindgren
      </HoverCardTrigger>
      <HoverCardContent>
        <p className="text-sm font-semibold text-foreground">Nora Lindgren</p>
        <p className="mt-1 text-sm text-text-secondary">Product designer at WunderUI.</p>
      </HoverCardContent>
    </HoverCard>
  )
}

Expected result: You see the link @noralindgren. Pointing at it or focusing it opens a small card with a name and a line of text; moving away or pressing Escape closes it.

When to use

Use Hover Card for

  • A summary of what a link points to, such as a person, a project or an issue, shown without leaving the page
  • Extra detail that is nice to have, where everything in the card is also on the page the link goes to

Use something else for

  • Tooltip for a short label for an icon or a control
  • Popover for content people click into, such as a form or a list of actions
  • Sheet for a detail view people open on purpose

Trigger

The trigger is the thing the card is about. A link is the default, because a click or tap still reaches the full page, and an avatar or a button works the same way.

Content state

A card that loads its content shows a skeleton of the final layout while it waits, and a short line with the way on when the preview cannot be loaded.

Keyboard interactions

The trigger is a link, so the browser provides focus and activation. The card itself is not focusable and not in the tab order.

TaborShiftTab
Moves focus to the trigger and opens the card; moving focus away closes it.
Enter
Follows the link of the trigger.
Escape
Closes the card.

Behavior and motion

What the card does with the pointer, focus, content and motion.

Opening
The card opens 100 ms after the pointer enters the trigger or it gets keyboard focus. The underlying default of 600 ms feels as if the preview never loads, and you can change the delay.
Closing
The card closes 100 ms after the pointer leaves both the trigger and the card, so you can move onto the card and select text. Escape closes it at once.
Touch
Touch screens can't hover, so a tap follows the link. The preview is an extra: everything in it must also be on the page the link goes to.
Not a dialog
Focus never moves into the card and it isn't announced as a popup. Don't put anything in it that people must reach with the keyboard.
Position and size
The card opens below the trigger, centred, 8 px away and 288 px wide. Set the side to open it above or beside the trigger; it flips when there is no room.
Previews in these docs
The card is portalled to the end of the document. The previews on this page draw it inside the preview instead and start open: move the pointer off the trigger and it closes.
Opening and closing
The card fades in and scales up from 97 % quickly, and leaves with a fade and a scale down to 99 %.
Reduced motion
With reduced motion the scale is off and the card only fades in and out.

Anatomy

The parts of a hover card, numbered in the figure. The card is a plain container: what it holds is up to you.

  • data-slot="hover-card"

    Holds the open state and links the trigger to the card. Control it yourself or leave it uncontrolled; it renders nothing itself.

  • data-slot="hover-card-trigger"

    The link or element the card is about, usually an anchor. The card opens when the pointer rests on it for 100 ms or when it gets keyboard focus.

  • data-slot="hover-card-content"

    The card. It brings its own portal and positioner, is 288 px wide and opens 8 px below the trigger, centred, and holds a summary: a name, a line or two and a status.

Best practices

  • Do

    Give the trigger an href to the full page. A click, a tap and a screen reader still get there, and the preview stays an extra.

  • Do

    Keep the content to a summary that fits the fixed width: an avatar, a name and one or two lines, or a title with a status.

  • Do

    Show a skeleton while the content loads and a short line when it cannot be loaded, so the card never opens empty.

  • Don’t

    Don't put buttons, fields or links in a Hover Card. Touch screens can't hover and the card isn't in the tab order; use a Popover for interactive content.

  • Don’t

    Don't put information in it that people need to finish a task. Everything in the card must also be on the page the link goes to.

  • Don’t

    Don't use it for the name of an icon. A Tooltip is for a short label on a control.

API reference

Hover Card wraps the Base UI preview card and passes its props on. The root takes the open state; the trigger and content also take a class name, style and a render prop.

Holds the open state and links the trigger to the card. Control it yourself or leave it uncontrolled; it renders nothing itself.

PropTypeDefaultDescription
openboolean—Whether the preview card is currently open.
defaultOpenbooleanfalseWhether the preview card is initially open. To render a controlled preview card, use the prop instead.
onOpenChange(open, eventDetails) => void—Event handler called when the preview card is opened or closed.
actionsRefRefObject<PreviewCardRoot.Actions | null>—A ref to imperative actions. - : Unmounts the preview card popup. - : Closes the preview card imperatively when called.
childrenReactNode | PayloadChildRenderFunction<Payload>—The content of the preview card. This can be a regular React node or a render function that receives the of the active trigger.
defaultTriggerIdstring | null—ID of the trigger that the preview card is associated with. This is useful in conjunction with the prop to create an initially open preview card.
handlePreviewCardHandle<Payload>—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.
onOpenChangeComplete(open) => void—Event handler called after any animations complete when the preview card is opened or closed.
triggerIdstring | null—ID of the trigger that the preview card is associated with. This is useful in conjunction with the prop to create a controlled preview card. There's no need to specify this prop when the preview card is uncontrolled (that is, when t…

The link or element the card is about, usually an anchor. The card opens when the pointer rests on it for 100 ms or when it gets keyboard focus.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
delaynumber100How long the pointer must rest on the trigger before the card opens, in milliseconds. 100 by default.
closeDelaynumber100How long after the pointer has left the trigger and the card before the card closes, in milliseconds. 100 by default.
handlePreviewCardHandle<Payload>—A handle to associate the trigger with a preview card.
payloadPayload—A payload to pass to the preview card when it is opened.

The card. It brings its own portal and positioner, is 288 px wide and opens 8 px below the trigger, centred, and holds a summary: a name, a line or two and a status.

PropTypeDefaultDescription
side"left" | "right" | "bottom" | "top" | "inline-end" | "inline-start""bottom"The side of the trigger the card opens on: , , or . It flips to the other side when there is no room.
sideOffsetnumber | OffsetFunction8The distance between the trigger and the card in pixels. 8 by default.
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("hover-card")
Installnpx wunderui-cli add hover-card

The full library index for assistants is at /llms.txt.