---
id: "packages/active-ui/hover-card"
title: "HoverCard"
description: "A preview of what a link points to, shown while the pointer rests on it or it has keyboard focus."
url: "/packages/active-ui/hover-card"
locale: "en"
revision: "ff8e2793eb5ef9f2"
---

# HoverCard

A hover card shows a preview of a link's destination, such as a person's profile or a document's
summary, while the reader hovers or focuses the link. It adds to the link, it never replaces it:
everything in the preview must also be reachable by following the link, because touch screens and
many readers never see it. It is built on Base UI's preview card.

**Example: A preview of a profile link**

Client: Runs entirely in your browser. Source: `examples/ui/hover-card.tsx`.

```tsx
// apps/docs/examples/ui/hover-card.tsx
'use client';

import {
  Avatar,
  AvatarFallback,
} from '@workspace/active-ui/components/primitives/avatar';
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from '@workspace/active-ui/components/primitives/hover-card';

/**
 * A preview of what a link points to, shown while the pointer rests on the
 * link or the link has keyboard focus. The preview only adds to the link:
 * everything in it is also on the page the link opens.
 */
export default function HoverCardExample() {
  return (
    <p className="text-sm">
      Last changed by{' '}
      <HoverCard>
        <HoverCardTrigger
          href="#hover-card-profile"
          className="font-medium underline underline-offset-4"
        >
          Sam de Vries
        </HoverCardTrigger>
        <HoverCardContent className="w-72">
          <div className="flex gap-3">
            <Avatar>
              <AvatarFallback>SV</AvatarFallback>
            </Avatar>
            <div className="flex flex-col gap-1">
              <p className="font-medium">Sam de Vries</p>
              <p className="text-muted-foreground text-sm">
                Scheme administrator since March 2024.
              </p>
              <p className="text-muted-foreground text-xs">
                12 schemes · Utrecht office
              </p>
            </div>
          </div>
        </HoverCardContent>
      </HoverCard>{' '}
      on 14 October.
    </p>
  );
}
```

## Usage

```tsx
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from '@workspace/active-ui/components/primitives/hover-card';

<HoverCard>
  <HoverCardTrigger href="/people/sam">Sam de Vries</HoverCardTrigger>
  <HoverCardContent>Scheme administrator since March 2024.</HoverCardContent>
</HoverCard>;
```

## Anatomy

- `HoverCard`: the open state.
- `HoverCardTrigger`: a link (`<a>`); give it an `href`. `delay` (default `600` ms) and
  `closeDelay` (default `300` ms) set how long the pointer must rest or leave.
- `HoverCardContent`: the preview, placed by `side` (default `bottom`) and `align`. It is
  `16rem` wide by default; set a width with `className`.

## What your application provides

- The link and the page it opens, with everything the preview shows.
- The preview content. Keep it short and without actions: buttons in a card that disappears when
  the pointer leaves are hard to reach.

## Accessibility and keyboard

- The trigger is an ordinary link: `Tab` reaches it and `Enter` follows it.
- Keyboard focus on the link opens the preview as hover does; `Escape` closes it.
- The preview is supplementary and not announced as part of the link; the link text must say
  where it goes.

## API

### HoverCardContent

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `align` | `Align` | no | How to align the popup relative to the specified side. |
| `alignOffset` | `number \| OffsetFunction` | no | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.  The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. |
| `render` | `ComponentRenderFn<HTMLProps, PreviewCardPopupState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | 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` | `Side` | no | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
| `sideOffset` | `number \| OffsetFunction` | no | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.  The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. |

### Other parts

**HoverCard**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<PreviewCardRootActions \| null>` | no | A ref to imperative actions. - `unmount`: Ends the closing phase of the preview card after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the preview card completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the preview card imperatively when called. |
| `children` | `PayloadChildRenderFunction<unknown> \| ReactNode` | no | 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` | no | Whether the preview card is initially open.  To render a controlled preview card, use the `open` prop instead. |
| `defaultTriggerId` | `string \| null` | no | 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<unknown>` | no | 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)` | no | Event handler called when the preview card is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` | no | Event handler called after any animations complete when the preview card is opened or closed. |
| `open` | `boolean` | no | Whether the preview card is currently open. |
| `triggerId` | `string \| null` | no | 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 the `open` prop is not set). |

**HoverCardTrigger**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | no | How long to wait before closing the preview card. Specified in milliseconds. |
| `delay` | `number` | no | How long to wait before the preview card opens. Specified in milliseconds. |
| `handle` | `PreviewCardHandle<unknown>` | no | A handle to associate the trigger with a preview card. |
| `payload` | `unknown` | no | A payload to pass to the preview card when it is opened. |
| `render` | `ComponentRenderFn<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, PreviewCardTriggerState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | 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. |

> [!NOTE]
> **Based on shadcn/ui**
>
> This page adapts the Hover Card documentation of shadcn/ui (MIT licence) to
> this package; see [Third-party notices](/third-party-notices).