Hover Card

For sighted users to preview content available behind a link.

Basic Hover Card

User Profile Preview

Show user details on hover without navigating away.

JDJohn Doe

Positioning

Usage

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

<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="link">@username</Button>
  </HoverCardTrigger>
  <HoverCardContent className="w-80">
    <div className="flex gap-4">
      <Avatar>
        <AvatarFallback>UN</AvatarFallback>
      </Avatar>
      <div>
        <h4 className="font-semibold">User Name</h4>
        <p className="text-sm text-muted-foreground">
          Description text here.
        </p>
      </div>
    </div>
  </HoverCardContent>
</HoverCard>

{/* With positioning */}
<HoverCardContent side="top" align="start">
  ...
</HoverCardContent>

Sidecar

The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/hover-card.md and shipped inside the published @gradeui/ui tarball.

---
name: HoverCard
import: "@gradeui/ui"
subcomponents: [HoverCardTrigger, HoverCardContent]
props:
  - HoverCard: open?, defaultOpen?, onOpenChange?, openDelay? (default 700), closeDelay? (default 300)
  - HoverCardTrigger: asChild?: boolean — usually a Link or Button
  - HoverCardContent: side?, align?, sideOffset?, alignOffset?, className?
when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
composes_with: [Avatar (user preview), Card (richer content), Link (the trigger)]
aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card]
---

```jsx
// User mention preview — pointer-only enrichment.
<HoverCard>
  <HoverCardTrigger asChild>
    <a href="/u/elena" className="font-medium underline">@elena</a>
  </HoverCardTrigger>
  <HoverCardContent className="w-72">
    <Row gap="sm" align="start">
      <Avatar>
        <AvatarImage src="/avatars/elena.png" />
        <AvatarFallback>EO</AvatarFallback>
      </Avatar>
      <Stack gap="xs">
        <span className="font-semibold">Elena Okafor</span>
        <span className="text-sm text-muted-foreground">
          Design lead · Joined Mar 2025
        </span>
      </Stack>
    </Row>
  </HoverCardContent>
</HoverCard>
```

Separator

Callout