HoverCard

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
  HoverCardHeader,
  HoverCardTitle,
  HoverCardDescription,
  HoverCardBody,
  HoverCardFooter,
  HoverCardArrow,
} from "@tessinaui/ui";

<HoverCard>
  <HoverCardTrigger render={<button>@blaz</button>} />
  <HoverCardContent side="bottom" align="start">
    <HoverCardHeader leading={<Avatar initials="BZ" />}>
      <HoverCardTitle>Blaz Zorcic</HoverCardTitle>
      <HoverCardDescription>Designer · Building TessinaUI.</HoverCardDescription>
    </HoverCardHeader>
    <HoverCardFooter>
      <Button variant="outline" size="xs">Message</Button>
      <Button size="xs">Follow</Button>
    </HoverCardFooter>
    <HoverCardArrow />
  </HoverCardContent>
</HoverCard>

Examples

Default

A user profile preview with an avatar, description, metadata, and footer actions.

Sizes

Four widths — sm, md, lg, and xl — each pairing a fixed width with a text scale.

Rounded

Corner radius from none to full, matched to the trigger for visual cohesion.

Intent border

Opt into a coloured border with intent + showIntentBorder for status previews.

Positioning

Place the card on any side of the trigger — top, right, bottom, or left.

Loading

HoverCardSkeleton mirrors the card's avatar, text, and optional stats while content loads.

When to use HoverCard vs. Tooltip vs. Popover

Touch behaviour. HoverCard is mouse/keyboard-only. On touch devices Base UI swallows the hover gesture so the trigger just behaves like a normal button. If you need an equivalent on touch, pair it with a Popover triggered by click, or surface the same content elsewhere.

Anatomy

Only HoverCard, HoverCardTrigger, and HoverCardContent are required. Everything else composes optionally inside HoverCardContent.

<HoverCard>
  <HoverCardTrigger>…</HoverCardTrigger>
  <HoverCardContent>
    <HoverCardHeader>
      <HoverCardTitle />
      <HoverCardDescription />
    </HoverCardHeader>
    <HoverCardBody />
    <HoverCardFooter />
    <HoverCardArrow />
  </HoverCardContent>
</HoverCard>

Size

Intent

intent drives the optional border colour (when showIntentBorder is on) and the arrow's stroke. The popup keeps a neutral border by default — opt in with showIntentBorder for status previews.

Rounded

Positioning

HoverCardContent accepts side (top | right | bottom | left), align (start | center | end), sideOffset (px gap from trigger, default 8), and alignOffset (px shift along the side, default 0).

<HoverCardContent side="right" align="start" sideOffset={12}>
  …
</HoverCardContent>

Delays

Pass delay (open) and closeDelay (close) on the root, in milliseconds. Defaults match Base UI: delay = 600, closeDelay = 300.

<HoverCard delay={300} closeDelay={150}>
  …
</HoverCard>

The values propagate to HoverCardTrigger via context — override per-trigger if you have multiple triggers in one card group.

Header slots

HoverCardHeader takes optional leading (avatar / icon) and trailing (badge / status) slots in addition to its title + description children.

<HoverCardHeader
  leading={<Avatar initials="BZ" />}
  trailing={<Badge variant="dot" color="success" />}
>
  <HoverCardTitle>Blaz Zorcic</HoverCardTitle>
  <HoverCardDescription>Online now</HoverCardDescription>
</HoverCardHeader>

Matching button corners to the card

HoverCardFooter is a generic slot — buttons inside don't auto-inherit the card's rounded. Pass rounded explicitly on each button to keep its corners flowing into the card edge:

<HoverCard rounded="none">
  <HoverCardTrigger render={<button>@blaz</button>} />
  <HoverCardContent>
    …
    <HoverCardFooter>
      {/* match the HoverCard's rounded prop */}
      <Button variant="outline" size="xs" rounded="none">Message</Button>
      <Button variant="primary" size="xs" rounded="none">Follow</Button>
    </HoverCardFooter>
  </HoverCardContent>
</HoverCard>

Controlled

HoverCard accepts open, defaultOpen, and onOpenChange.

const [open, setOpen] = React.useState(false);

<HoverCard open={open} onOpenChange={setOpen}>
  …
</HoverCard>

Accessibility

• Built on @base-ui/react/preview-card — opens on hover or keyboard focus of the trigger.
• The card's content is announced when focus moves into it; otherwise it remains presentational while the trigger is hovered.
• Pressing Escape closes the card.
• On touch input the card does not open — the trigger is announced as a normal button.
• Use intent="error" or "warning" with showIntentBorder to give status previews a visual signal that complements text content.

RTL

Pass dir="rtl" to the root. Header alignment, the leading/trailing slots, and footer button order all flip to follow the reading direction.

<HoverCard dir="rtl">
  <HoverCardTrigger render={<button>@blaz</button>} />
  <HoverCardContent>
    <HoverCardHeader>
      <HoverCardTitle>بلاز زورتشيتش</HoverCardTitle>
      <HoverCardDescription>مصمم · يبني TessinaUI.</HoverCardDescription>
    </HoverCardHeader>
    <HoverCardArrow />
  </HoverCardContent>
</HoverCard>

API Reference

HoverCard (root)

HoverCardContent

HoverCardHeader

HoverCardTrigger

Renders a <button>. Use render={<a href="…" />} to swap in a link, or render={<MyComponent />} for any element. Accepts delay / closeDelay to override the values inherited from the root.

Sub-components

HoverCardTitle, HoverCardDescription, HoverCardBody, HoverCardFooter, HoverCardArrow, HoverCardBackdrop — all accept className and any HTML props.

Notes

• Built on @base-ui/react/preview-card — Base UI's name for the HoverCard primitive.
• Enter/exit animations use Base UI's data-[starting-style] / data-[ending-style] plus position-aware data-[side=*] attributes, so the popup "lifts off" from whichever side it opens on.
• The arrow is drawn as a single rotated square — no SVG — so it inherits the surface colour and (when showIntentBorder is on) the intent border colour automatically.