Hover Card

A card that previews what is behind a link while the pointer rests on it.

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"

export default function HoverCardDemo() {
  return (
    <HoverCard>
      <HoverCardTrigger delay={200} closeDelay={100} render={<Button variant="link" />}>
        @arc1hq
      </HoverCardTrigger>
      <HoverCardContent>
        <HStack gap={3}>
          <Avatar>
            <AvatarImage src="https://github.com/arc1hq.png" alt="@arc1hq" />
            <AvatarFallback>A1</AvatarFallback>
          </Avatar>
          <VStack gap={0.5}>
            <Text weight="semibold">@arc1hq</Text>
            <span>The team behind arene, a React design system on Base UI and StyleX.</span>
            <Text size="xs" tone="muted">
              github.com/arc1hq
            </Text>
          </VStack>
        </HStack>
      </HoverCardContent>
    </HoverCard>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/hover-card

Needs the arene setup first.

Usage

import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
<HoverCard>
  <HoverCardTrigger href="https://github.com/arc1hq">@arc1hq</HoverCardTrigger>
  <HoverCardContent>
    The team behind arene, a React design system on Base UI and StyleX.
  </HoverCardContent>
</HoverCard>

Composition

HoverCard
├── HoverCardTrigger
└── HoverCardContent      portal + positioner + popup

HoverCardTrigger renders an <a>. Pass render to anchor the card to a different element.

A hover card opens on hover and on keyboard focus, never on press. A touch screen has no hover, so the card never opens there. Put nothing in it that a reader cannot also reach another way.

Trigger delays

Use delay and closeDelay on the trigger to set how long the pointer has to rest before the card opens, and how long it stays open after the pointer leaves. closeDelay keeps the card open while the pointer crosses the gap into it.

import { Button } from "@/components/ui/button"
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { HStack } from "@/components/ui/stack"

export default function HoverCardDelay() {
  return (
    <HStack gap={2} wrap="wrap" justify="center">
      <HoverCard>
        <HoverCardTrigger delay={0} closeDelay={0} render={<Button variant="outline" />}>
          Immediate
        </HoverCardTrigger>
        <HoverCardContent>Opens the moment the pointer lands.</HoverCardContent>
      </HoverCard>
      <HoverCard>
        <HoverCardTrigger render={<Button variant="outline" />}>Default</HoverCardTrigger>
        <HoverCardContent>Waits 600ms to open and 300ms to close.</HoverCardContent>
      </HoverCard>
      <HoverCard>
        <HoverCardTrigger delay={1000} closeDelay={600} render={<Button variant="outline" />}>
          Patient
        </HoverCardTrigger>
        <HoverCardContent>Waits a second, then stays while you cross the gap.</HoverCardContent>
      </HoverCard>
    </HStack>
  )
}

Sides

Use side on HoverCardContent to pick the edge it opens from, and align to slide it along that edge. Base UI flips the side when there is no room.

import { Button } from "@/components/ui/button"
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
import { HStack, VStack } from "@/components/ui/stack"

const sides = ["top", "right", "bottom", "left"] as const

export default function HoverCardSides() {
  return (
    <HStack gap={2} wrap="wrap" justify="center">
      {sides.map((side) => (
        <HoverCard key={side}>
          <HoverCardTrigger delay={100} closeDelay={100} render={<Button variant="outline" />}>
            {side}
          </HoverCardTrigger>
          <HoverCardContent side={side}>
            <VStack gap={1}>
              <span>Preview</span>
              <span>This card opens on the {side} of its trigger.</span>
            </VStack>
          </HoverCardContent>
        </HoverCard>
      ))}
    </HStack>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI PreviewCard part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className.

HoverCard

PropTypeDefault
openboolean—
defaultOpenbooleanfalse
onOpenChange(open: boolean, details) => void—
handlePreviewCardHandle—

HoverCardTrigger

PropTypeDefault
delaynumber600
closeDelaynumber300
payloadPayload—

HoverCardContent

PropTypeDefault
side"top" | "bottom" | "left" | "right""bottom"
sideOffsetnumber4
align"start" | "center" | "end""center"
alignOffsetnumber0

The card is 16rem wide and clamped to --available-width, so it narrows rather than overflowing a phone-width viewport. Change the width through xstyle.

Data attributes

AttributeOnEffect
data-slot="hover-card-content"the popupPopup surface
data-sidethe popupWhich way it slides in from
data-starting-style, data-ending-stylethe popupBase UI writes them while the card animates
data-open, data-closedthe popupBase UI writes them