Hover Card
FreeA card that previews what a link points to when the pointer rests on it or the keyboard focuses it.
npx wunderui-cli add hover-cardPlayground
Installation
npx wunderui-cli add hover-cardWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
HoverCard,
HoverCardContent,
HoverCardTrigger,
} from "@/components/ui/hover-card"Then use it:
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
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.
- TaborShift+Tab
- 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.
- 1data-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.
- 2data-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.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Whether the preview card is currently open. |
| defaultOpen | boolean | false | Whether 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. |
| actionsRef | RefObject<PreviewCardRoot.Actions | null> | — | A ref to imperative actions. - : Unmounts the preview card popup. - : Closes the preview card imperatively when called. |
| children | ReactNode | 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. |
| defaultTriggerId | string | 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. |
| handle | PreviewCardHandle<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. |
| triggerId | string | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (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. |
| delay | number | 100 | How long the pointer must rest on the trigger before the card opens, in milliseconds. 100 by default. |
| closeDelay | number | 100 | How long after the pointer has left the trigger and the card before the card closes, in milliseconds. 100 by default. |
| handle | PreviewCardHandle<Payload> | — | A handle to associate the trigger with a preview card. |
| payload | Payload | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| sideOffset | number | OffsetFunction | 8 | The distance between the trigger and the card in pixels. 8 by default. |
| render | ReactElement | (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.
get_component("hover-card")npx wunderui-cli add hover-cardThe full library index for assistants is at /llms.txt.