Preview Card

A preview card shows what a link points to, like a profile, an article, or a definition, when the pointer rests on the link or it gets focus. Use it to help someone decide whether to follow the link. For a short label on an icon button, use Tooltip. For anything with controls inside, use Popover.

Preview#

import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,
} from "@/components/ui/cubby-ui/preview-card";
import { Avatar, AvatarFallback } from "@/components/ui/cubby-ui/avatar";

Installation#

npxnpx shadcn@latest add @cubby-ui/preview-card

Usage#

import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,
} from "@/components/ui/cubby-ui/preview-card";

<PreviewCard>
  <PreviewCardTrigger />
  <PreviewCardContent />
</PreviewCard>

Composition#

PreviewCard
├── PreviewCardTrigger
└── PreviewCardContent
    ├── PreviewCardMedia
    ├── PreviewCardTitle
    └── PreviewCardDescription

PreviewCardContent renders the portal, positioner, popup, and viewport. The media, title, and description parts are optional; put any markup you like inside the content.

PreviewCardTrigger renders an <a>. Give it an href so the link still works for anyone who clicks, taps, or never sees the card.

Examples#

Link Preview#

Use PreviewCardMedia to run an image edge to edge along the top, in the 1.91:1 ratio of a page's og:image.

import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,
  PreviewCardMedia,
  PreviewCardTitle,

Shared Card#

Pass one handle from createPreviewCardHandle to a PreviewCard and any number of triggers, and the card glides between them, rendering each trigger's payload.

"use client";
 
import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,

const handle = createPreviewCardHandle<Person>();
 
function Contributors({ people }: { people: Person[] }) {
  return (
    <>
      {people.map((person) => (
        <PreviewCardTrigger
          key={person.id}
          handle={handle}
          payload={person}
          href={person.url}
        >
          {person.name}
        </PreviewCardTrigger>
      ))}
      <PreviewCard handle={handle}>
        {({ payload }) => (
          <PreviewCardContent>{payload?.name}</PreviewCardContent>
        )}
      </PreviewCard>
    </>
  );
}

The triggers can sit anywhere in the tree, and a long list mounts one card instead of one per row.

Arrow#

Set arrow to point the card at its trigger.

import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,
  PreviewCardTitle,
  PreviewCardDescription,

Wrapping Text#

When the link wraps across lines, the card anchors to the line under the pointer, with no extra props.

import {
  PreviewCard,
  PreviewCardTrigger,
  PreviewCardContent,
  PreviewCardTitle,
  PreviewCardDescription,

Accessibility#

Keep essential information out of the card#

Touch screens have no hover, so tapping the trigger follows the link and the card never opens. Anything a reader needs belongs on the page itself.

Keyboard and motion#

Focusing the trigger opens the card after the same delay as hover, without animation, and Escape closes it. With reduced motion on, the card fades in and out and switching triggers crossfades the content, with no scale, blur, glide, or nudge.

API Reference#

The PreviewCard component is built on top of Base UI's PreviewCard. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI PreviewCard documentation.

Utilities#

createPreviewCardHandle#

Creates a handle that connects one PreviewCard to triggers anywhere in the tree. Pass a type argument to type each trigger's payload. The handle also has open(triggerId), close(), and isOpen for driving the card from your own code.

Props#

PreviewCardTrigger#

Link that opens the card. Wraps Base UI's PreviewCard.Trigger.

PreviewCardContent#

The card itself. Composes PreviewCard.Portal, PreviewCard.Positioner, PreviewCard.Popup, and PreviewCard.Viewport, and optionally PreviewCard.Arrow. Props are forwarded to PreviewCard.Popup.

Upgrading#

If you're reinstalling over an earlier version, check these changes: