---
title: Hover Card
description: For sighted users to preview content available behind a link.
icon: info
author:
  name: imskyleen
  url: https://github.com/imskyleen
search:
  keywords: [preview card, popover on hover]
related:
  - /tooltip
  - /popover
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Base UI', url: 'https://base-ui.com/react/components/preview-card' },
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/hover-card' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/hover-card
```

<ComponentPreview name="hover-card-demo" description="Preview card revealed on hover — typical avatar + bio pattern." />

### Positioning

<ComponentPreview
  name="hover-card-side-demo"
  description="Render the hover card on any side (top / right / bottom / left) via the `side` prop."
/>

## When to use

Use this decision tree to determine when to use the Hover Card component:

```mermaid
graph TD;
    A[❓ Need hover-based content display?] --> B{What trigger method?};
    B --> C[✅ Hover/mouse over];
    B --> D[⚠️ Click interaction];
    B --> E[⚠️ Focus interaction];

    C --> F[❓ What content type?];
    D --> G[⚠️ Use Popover/Dialog instead];
    E --> H[⚠️ Use Tooltip instead];

    F --> I[✅ Rich content/previews];
    F --> J[✅ User profiles/cards];
    F --> K[⚠️ Simple text hints];
    F --> L[✅ Interactive elements];

    I --> M[❓ Mobile considerations?];
    J --> M;
    K --> N[⚠️ Use Tooltip instead];
    L --> O[❓ Content complexity?];

    M --> P[⚠️ Mobile users present?];
    M --> Q[ℹ️ Desktop-only interface];

    O --> R[✅ Complex interactive content];
    O --> S[ℹ️ Simple interactive elements];

    P --> T[⚠️ Provide click alternative];
    Q --> U[✅ Implement HoverCard];
    R --> V[✅ Use HoverCard with delays];
    S --> U;

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,I,J,L,R,U,V recommended;
    class D,E,G,H,K,N,P,T discouraged;
    class A,B,F,M,O decision;
    class Q,S neutral;
```

## Usage

```tsx
<HoverCard>
  <HoverCardTrigger>Hover Card Trigger</HoverCardTrigger>
  <HoverCardContent>Hover Card Content</HoverCardContent>
</HoverCard>
```

## Props

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://base-ui.com/react/components/preview-card" text="Docs" />
  <ExternalLink href="https://base-ui.com/react/components/preview-card#api-reference" text="API Reference" />
</div>

## Keyboard interactions

| Key                         | Action                                              |
| --------------------------- | --------------------------------------------------- |
| `Tab` to `HoverCardTrigger` | Opens the hover card (keyboard-focus trigger).      |
| `Shift+Tab` off the trigger | Closes the hover card.                              |
| `Escape`                    | Closes the hover card without moving focus.         |
| Pointer hover / leave       | Opens after `openDelay`, closes after `closeDelay`. |

## Accessibility

- Hover cards are **supplementary** — put the same content on the page in an accessible form (link target, expandable
  section) so touch and reduced-motion users aren't excluded.
- The trigger must be a focusable element (`<a href>` is typical since hover cards preview links). Use the `render`
  prop to render the trigger as whatever semantic element you need.
- Content is wired via `aria-describedby` so screen readers announce the preview when the trigger has focus.
- Prefer `Popover` when the content contains interactive controls — hover cards auto-close on leave and interactive
  content becomes difficult to reach.

## Controlled vs uncontrolled

Uncontrolled — typical case, hover cards time their own open/close:

```tsx lineNumbers
<HoverCard>
  <HoverCardTrigger render={<a href="/users/bm">@malinskibeniamin</a>} />
  <HoverCardContent>{/* preview card */}</HoverCardContent>
</HoverCard>
```

Controlled — force open/closed for demos or during a guided tour:

```tsx lineNumbers
const [open, setOpen] = useState(false);

<HoverCard open={open} onOpenChange={setOpen}>
  <HoverCardTrigger render={<a href="/users/bm">@malinskibeniamin</a>} />
  <HoverCardContent>{/* preview card */}</HoverCardContent>
</HoverCard>;
```

## Credits

- We use [Base UI](https://base-ui.com/react/components/preview-card) for the hover card component.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/hover-card) for the hover card style.