# HoverCard
- **Category:** Overlay (`overlay`)
- **Slug:** `overlay/hover-card`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { HoverCard } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/overlay/hover-card
> A rich preview panel revealed on hover — an entity card for a person, repo, or resource that a plain tooltip can't hold.
## When to use it
A HoverCard gives a **sighted, pointer-driven preview** of the entity behind a link — a user behind an @-mention, a repo behind its name, a resource behind an id. It's supplementary: everything in the card must be reachable another way, because it never opens on touch and shouldn't be relied on by keyboard-only users.
If the content is a **single line of text**, use a **[Tooltip](/overlay/tooltip)** — lighter, faster, and it opens on focus too. If the panel holds **interactive controls** the user acts on, it's not a HoverCard at all — use a **[Popover](/overlay/popover)** with a click trigger. HoverCard sits precisely between: richer than a tooltip, but read-only and hover-only.
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | no | — | — |
| `className` | `string` | no | — | — |
| `style` | `CSSProperties` | no | — | — |
## Examples
### Basics
Wrap the reference (a name, a mention) in `HoverCard.Trigger` and put the preview in `HoverCard.Content`. It opens after a 400ms hover — deliberate, so it doesn't fire on casual pointer travel.
```tsx
import { HoverCard, Avatar, Text, HStack, VStack, Link } from "@protocore/pds";
export default function HoverCardBasics() {
return (
Last signed by{" "}
@ana.pop
Ana Pop
Root operator · 214 signed blocks
{" "}
at 14:02 UTC.
);
}
```
### Resource preview
The card can hold structured content — status badges, metrics, meta — laid out with the same primitives you'd use anywhere. Keep it a glanceable summary, not a full record.
```tsx
import { HoverCard, Text, HStack, VStack, Badge, Link } from "@protocore/pds";
import { GitBranch, Star } from "lucide-react";
export default function HoverCardRepoPreview() {
return (
Pinned service:{" "}
protocore/consensus
protocore/consensus
BFT ordering service for the shared ledger.
healthy
1.2k
main
);
}
```
## Do & don't
**Do**
- Preview an entity — person, repo, resource — behind a link or mention.
- Keep it a glanceable summary that duplicates info available elsewhere.
- Let the 400ms delay prevent it firing during casual pointer movement.
- Use structured layout (avatar, badges, meta) that a tooltip couldn't hold.
**Don't**
- Put buttons, inputs, or links the user must click inside — use a Popover.
- Hide essential information only in the card — it never opens on touch or focus-only flows.
- Use it for a one-line hint — that's a Tooltip.
- Overfill it into a full detail view; link to the real page for that.
## Accessibility
**Keyboard**
| Keys | Action |
| --- | --- |
| `Tab` | Focusing the trigger link also opens the card after the delay. |
| `Esc` | Dismisses the open card. |
**Notes**
- Primarily a pointer-hover affordance; it does not open on touch, so never gate essential info behind it.
- The trigger should be a real link or button so keyboard users can still reach the underlying destination.
- Opens after ~400ms hover and closes on pointer-leave or Esc; content outside stays interactive.
- Treat the card as decorative enhancement over an already-complete interface.
## Related
`tooltip`, `popover`, `avatar`, `card`
---
© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/