# Hover Card

A rich preview popup shown on hovering a trigger.

- Category: Core Elements
- Page: https://wunderui.com/components/hover-card
- Tier: Free

## Install

```bash
npx wunderui-cli add hover-card
```

## Import

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

## Minimal usage

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.

## Usage

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { CalendarDays } from "lucide-react"

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="/team/nora-lindgren" />} className="font-medium text-text-link underline-offset-4 hover:underline">
        @noralindgren
      </HoverCardTrigger>
      <HoverCardContent>
        <div className="flex gap-3">
          <Avatar size="lg" color="purple">
            <AvatarFallback>NL</AvatarFallback>
          </Avatar>
          <div className="flex min-w-0 flex-col gap-0.5">
            <p className="text-sm font-semibold text-foreground">Nora Lindgren</p>
            <p className="text-xs text-text-secondary">@noralindgren</p>
          </div>
        </div>
        <p className="mt-3 text-sm text-text-secondary">Product designer at WunderUI. Works on the design system and the docs.</p>
        <p className="mt-3 flex items-center gap-1.5 text-xs text-text-secondary">
          <CalendarDays className="size-3.5" />
          Joined March 2024
        </p>
      </HoverCardContent>
    </HoverCard>
  )
}
```

## 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

- [Tooltip](https://wunderui.com/components/tooltip) for a short label for an icon or a control
- [Popover](https://wunderui.com/components/popover) for content people click into, such as a form or a list of actions
- [Sheet](https://wunderui.com/components/sheet) for a detail view people open on purpose

## Keyboard

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

| Key | Action |
|---|---|
| `Tab` or `Shift+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

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

- `HoverCard`: Holds the open state and links the trigger to the card. Control it yourself or leave it uncontrolled; it renders nothing itself.
- `HoverCardTrigger`: 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.
- `HoverCardContent`: 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.
- 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.
- 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 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 use it for the name of an icon. A Tooltip is for a short label on a control.

## API reference

### HoverCard

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<PreviewCardRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Unmounts the preview card popup. - `close`: Closes the preview card imperatively when called. |
| children | React.ReactNode \| PayloadChildRenderFunction<Payload> |  | 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 | false | 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<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. |
| onOpenChange | ((open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => 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 t… |

### HoverCardContent

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | "left" \| "right" \| "bottom" \| "top" \| "inline-end" \| "inline-start" | 'bottom' | The side of the trigger the card opens on: `top`, `right`, `bottom` or `left`. 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. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### HoverCardTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| closeDelay | number | 100 | How long after the pointer has left the trigger and the card before the card closes, in milliseconds. 100 by default. |
| delay | number | 100 | How long the pointer must rest on the trigger before the card opens, 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. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.AnchorHTMLAttributes attributes.

## Examples

### Trigger: a link, an avatar or a button

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { CalendarDays } from "lucide-react"

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="/team/nora-lindgren" />} className="font-medium text-text-link underline-offset-4 hover:underline">
        @noralindgren
      </HoverCardTrigger>
      <HoverCardContent>
        <div className="flex gap-3">
          <Avatar size="lg" color="purple">
            <AvatarFallback>NL</AvatarFallback>
          </Avatar>
          <div className="flex min-w-0 flex-col gap-0.5">
            <p className="text-sm font-semibold text-foreground">Nora Lindgren</p>
            <p className="text-xs text-text-secondary">@noralindgren</p>
          </div>
        </div>
        <p className="mt-3 text-sm text-text-secondary">Product designer at WunderUI. Works on the design system and the docs.</p>
        <p className="mt-3 flex items-center gap-1.5 text-xs text-text-secondary">
          <CalendarDays className="size-3.5" />
          Joined March 2024
        </p>
      </HoverCardContent>
    </HoverCard>
  )
}
```

### Content state: loaded, loading and unavailable

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { CalendarDays } from "lucide-react"

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="/team/nora-lindgren" />} className="font-medium text-text-link underline-offset-4 hover:underline">
        @noralindgren
      </HoverCardTrigger>
      <HoverCardContent>
        <div className="flex gap-3">
          <Avatar size="lg" color="purple">
            <AvatarFallback>NL</AvatarFallback>
          </Avatar>
          <div className="flex min-w-0 flex-col gap-0.5">
            <p className="text-sm font-semibold text-foreground">Nora Lindgren</p>
            <p className="text-xs text-text-secondary">@noralindgren</p>
          </div>
        </div>
        <p className="mt-3 text-sm text-text-secondary">Product designer at WunderUI. Works on the design system and the docs.</p>
        <p className="mt-3 flex items-center gap-1.5 text-xs text-text-secondary">
          <CalendarDays className="size-3.5" />
          Joined March 2024
        </p>
      </HoverCardContent>
    </HoverCard>
  )
}
```

## In context

### Mention in a comment

A mention is a link to a person. The card shows who it is without leaving the thread.

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

export function CommentWithMention() {
  return (
    <p className="text-sm text-text-secondary">
      Looks good to me.{" "}
      <HoverCard>
        <HoverCardTrigger render={<a href="/team/daniel-okafor" />} className="font-medium text-text-link underline-offset-4 hover:underline">
          @danielokafor
        </HoverCardTrigger>
        <HoverCardContent>
          <div className="flex gap-3">
            <Avatar size="lg" color="green">
              <AvatarFallback>DO</AvatarFallback>
            </Avatar>
            <div className="flex min-w-0 flex-col gap-0.5">
              <p className="text-sm font-semibold text-foreground">Daniel Okafor</p>
              <p className="text-xs text-text-secondary">@danielokafor</p>
            </div>
          </div>
          <p className="mt-3 text-sm text-text-secondary">Engineering lead at WunderUI. Owns the pricing page.</p>
        </HoverCardContent>
      </HoverCard>{" "}
      can you check the pricing page before we ship?
    </p>
  )
}
```

### Issue reference in a task

A reference to another task shows its title, status and assignee, so the reader knows what it is about before opening it.

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Badge } from "@/components/ui/badge"

export function IssueReference() {
  return (
    <p className="text-sm text-text-secondary">
      This task is blocked by{" "}
      <HoverCard>
        <HoverCardTrigger render={<a href="/issues/wui-482" />} className="font-medium text-text-link underline-offset-4 hover:underline">
          WUI-482
        </HoverCardTrigger>
        <HoverCardContent>
          <p className="text-xs text-text-secondary">WUI-482</p>
          <p className="mt-1 text-sm font-semibold text-foreground">Menu closes on the first click</p>
          <div className="mt-3 flex items-center justify-between gap-3">
            <Badge color="indigo" badgeStyle="light">
              In progress
            </Badge>
            <span className="flex items-center gap-2 text-xs text-text-secondary">
              <Avatar size="sm" color="green">
                <AvatarFallback>DO</AvatarFallback>
              </Avatar>
              Daniel Okafor
            </span>
          </div>
        </HoverCardContent>
      </HoverCard>
      , which fixes the first-click close.
    </p>
  )
}
```

### Owner in a project table

The owner of a project is a link to their profile. The card sits over the rows below it and closes when the pointer leaves.

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { CalendarDays } from "lucide-react"

export function OwnerColumn() {
  return (
    <div className="grid grid-cols-[1fr_1fr_auto] items-center gap-3 text-sm">
      <span className="font-medium text-foreground">Q4 roadmap</span>
      <HoverCard>
        <HoverCardTrigger render={<a href="/team/nora-lindgren" />} className="font-medium text-text-link underline-offset-4 hover:underline">
          Nora Lindgren
        </HoverCardTrigger>
        <HoverCardContent>
          <div className="flex gap-3">
            <Avatar size="lg" color="purple">
              <AvatarFallback>NL</AvatarFallback>
            </Avatar>
            <div className="flex min-w-0 flex-col gap-0.5">
              <p className="text-sm font-semibold text-foreground">Nora Lindgren</p>
              <p className="text-xs text-text-secondary">@noralindgren</p>
            </div>
          </div>
          <p className="mt-3 text-sm text-text-secondary">Product designer at WunderUI. Works on the design system and the docs.</p>
          <p className="mt-3 flex items-center gap-1.5 text-xs text-text-secondary">
            <CalendarDays className="size-3.5" />
            Joined March 2024
          </p>
        </HoverCardContent>
      </HoverCard>
      <span className="text-text-secondary">Nov 4</span>
    </div>
  )
}
```

## For AI agents

`get_component("hover-card")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
