# HoverCard

> A rich preview on hover or keyboard focus of a link: a person, a project, a record.

Category: Overlays. Docs page: https://rime.mjsons.net/components/hover-card

## Installation

```bash
npx shadcn@latest add KezLahd/rime/hover-card
```

HoverCard opens after a short delay (openDelay, 500ms) when the pointer rests on its trigger or the trigger takes keyboard focus, and closes a little after the pointer leaves (closeDelay, 200ms), so the pointer can travel onto the card. Touch never opens it: the trigger must work on its own.

The card is supplementary. It is tied to the trigger with aria-describedby while open and Esc dismisses it.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { HoverCard } from "@/components/ui";

<HoverCard trigger={<a href="/team/jane-cooper">@janecooper</a>}>
  …profile…
</HoverCard>
```

## Props: HoverCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` (required) | `ReactElement<TriggerProps>` |  | A link or button the card previews: a person's name, a project, a reference. |
| `children` (required) | `ReactNode` |  | The preview: a few lines of supporting detail. Never the only route to an action. |
| `openDelay` | `number` | `500` | ms of hover or focus before it opens. |
| `closeDelay` | `number` | `200` | ms after the pointer leaves before it closes, so it can travel onto the card. |
| `side` | `FloatSide` | `"bottom"` |  |
| `align` | `FloatAlign` | `"start"` |  |
| `width` | `number` | `300` | Panel width in px. |
| `inline` | `boolean` |  | Render the card open in the page flow under the trigger (docs, previews). |
| `className` | `string` |  |  |

## Examples

### Open

```tsx
<HoverCard inline trigger={<a href="/team/jane-cooper">@janecooper</a>}>
  <Avatar name="Jane Cooper" />
  <strong>Jane Cooper</strong>
  <span>Design lead on Project Atlas.</span>
</HoverCard>
```

### On hover and focus

Hover the name, or Tab to it.

```tsx
<p>Assigned to <HoverCard trigger={<a href="/team/jane-cooper">@janecooper</a>}>…</HoverCard> for review.</p>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--hover-card-pad` | `calc(16px * var(--density))` |
| `--hover-card-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease-out`, `--ink-body`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--text-small`, `--z-popover`.

## Accessibility

- Opens on keyboard focus as well as hover, and the card describes its trigger (aria-describedby).
- Esc closes it. Nothing inside it should be the only way to reach an action.
- Respects reduced motion: it fades in place.

## Do

- Use it on links whose target needs a glance before a click: people, projects, references.

## Don't

- Don't put buttons or forms in a hover card; use Popover.
- Don't use it on touch-first screens as the only way to see the detail.

Related: https://rime.mjsons.net/components/popover, https://rime.mjsons.net/components/tooltip, https://rime.mjsons.net/components/avatar