HoverCard

A preview of what a link points to, shown while the pointer rests on it or it has keyboard focus.

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.

A preview of a profile linkClient

Last changed by Sam de Vries on 14 October.

Full source examples/ui/hover-card.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#

Import from @workspace/active-ui/components/primitives/hover-card

All props come from the Base UI part this component is built on.

Props

align

Type: Align
Default: 'center'

How to align the popup relative to the specified side.

alignOffset

Type: number | OffsetFunction
Default: 0

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.

side

Type: Side
Default: 'bottom'

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

sideOffset

Type: number | OffsetFunction
Default: 0

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.

render

Type: ComponentRenderFn<…>ReactElement<…>

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.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Other parts#

All props come from the Base UI part this component is built on.

Props

triggerId

Type: 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 the open prop is not set).