Skip to content
Nexus Application Design nadesign

HoverCardPreview

<HoverCardPreview> is the Attio-style entity peek: hover an entity name in a list, see avatar + 3–5 properties + quick actions, all without leaving the list. Desktop-only; touch devices navigate directly.

import from "@na/ui/components/HoverCardPreview" ▶ Open in Storybook packages/ui/src/components/HoverCardPreview.tsx

When to use

  • Entity-name cells in list / table views (deal, person, agent, …).
  • Anywhere the user can identify what’s behind a name without committing to navigate.

Don’t use HoverCardPreview for: tooltips (Tooltip), modal-style detail (use a real route or a Sheet), or destructive actions inside the preview — only quick actions.

Basic

Owner: Acme Corp

 
<HoverCardPreview
  trigger={<a href={`/agents/${agent.id}`}>{agent.name}</a>}
  content={
    <div className="flex items-start gap-3">
      <Avatar size="lg"><AvatarFallback>AC</AvatarFallback></Avatar>
      <div>
        <div className="font-medium">{agent.name}</div>
        <div className="text-muted-foreground text-xs">5 deals · $128K</div>
        <HoverCardActions>
          <Button size="xs" variant="outline">Open</Button>
          <Button size="xs" variant="outline">Email</Button>
        </HoverCardActions>
      </div>
    </div>
  }
/>

API

Prop Type Default Description
trigger * ReactElement — The entity-name element. Must be focusable (a link or a button) — preview is keyboard-reachable, not just hover.
content * ReactNode — Preview body. Compose Avatar + properties + HoverCardActions.
openDelay number 200 Ms before the preview opens on hover.
closeDelay number 100 Ms before the preview closes on hover-out.
side "top" | "right" | "bottom" | "left" "bottom" Preferred placement.
align "start" | "center" | "end" "start" Anchor alignment.
sideOffset number — Pixels between trigger and preview.

HoverCardActions wraps the action row inside content for consistent gap + button sizing.

Design guidelines

✓ Do

  • Anchor on entity-name cells in lists — the highest-value spot for peek-on-hover.
  • Keep content scannable: avatar, name, 3–5 properties max, 1–2 actions.
  • Provide quick actions only (Open, Email, Copy link). Destructive actions belong on the record page.

✗ Don't

  • Use HoverCardPreview on every link. Reserve it for entity names.
  • Add destructive actions inside. Delete / Archive / Reset live on the record page.
  • Pad the preview with marketing copy. The user is mid-list — they want a glance, not a brochure.

Accessibility

  • Trigger must be focusable — a real link or button. Hover only on pointer devices; keyboard focus also opens the preview.
  • Preview content is described by the trigger’s accessible name; consider aria-describedby for important supplementary content.
  • Touch devices skip the preview and navigate directly (the trigger is a link, after all).

▶ Open HoverCardPreview stories in Storybook