# HoverCard

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - hover-card.variants — `hoverCardContentVariants` is…
- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
- hover-card.variants — `hoverCardContentVariants` is…

- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…

- hover-card.variants — `hoverCardContentVariants` is…

- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…

- hover-card.variants — `hoverCardContentVariants` is…

- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…

## Purpose

`<HoverCard>` and its sub-components (`<HoverCardTrigger>`, `<HoverCardPortal>`, `<HoverCardContent>`, `<HoverCardArrow>`) are the chassis hover-card primitives built on `@radix-ui/react-hover-card`. Use this for non-modal previews that open on hover or focus over the trigger and dismiss on hover-out or blur — link previews, user-mention bios, contextual mini-cards.

Distinct from `<Popover>`: HoverCard is hover-driven (mouse-only by spec; touch devices fall back to tap-to-open) with `openDelay` / `closeDelay` hysteresis. Distinct from `<Tooltip>`: HoverCard panels can hold rich content (multiple paragraphs, images, action links); Tooltip is a single short label.

## Features

- Opens on hover or focus over the trigger; closes on hover-out or blur.
- `openDelay` / `closeDelay` numeric hysteresis (default 700/300 ms — Radix defaults).
- Side / align positional API (`side`: top/right/bottom/left; `align`: start/center/end).
- Self-portals via `<HoverCardPortal>`.
- Optional `<HoverCardArrow>` decoration.
- Theme-driven cva via `useThemedVariants("HoverCardContent")`.
- All sub-components forward refs.
- `motion-reduce:animate-none` collapses the open/close animations under `prefers-reduced-motion: reduce`.

## Usage: Basic Example

```tsx
import {
    HoverCard,
    HoverCardContent,
    HoverCardTrigger,
} from "@suaveplan/react-ui";

export function MentionPreview() {
    return (
        <HoverCard>
            <HoverCardTrigger>@suaveplan</HoverCardTrigger>
            <HoverCardContent>
                Component library for the Suaveplan platform.
            </HoverCardContent>
        </HoverCard>
    );
}
```

## Usage: Advanced Example

```tsx
import {
    HoverCard,
    HoverCardArrow,
    HoverCardContent,
    HoverCardTrigger,
} from "@suaveplan/react-ui";

interface User {
    readonly handle: string;
    readonly displayName: string;
    readonly bio: string;
    readonly avatarUrl: string;
}

export function UserMention({ user }: { user: User }) {
    return (
        <HoverCard openDelay={400} closeDelay={200}>
            <HoverCardTrigger asChild>
                <a href={`/${user.handle}`}>@{user.handle}</a>
            </HoverCardTrigger>
            <HoverCardContent side="top" align="start" sideOffset={8}>
                <HoverCardArrow />
                <div className="flex gap-3">
                    <img
                        src={user.avatarUrl}
                        alt=""
                        className="h-10 w-10 rounded-full"
                    />
                    <div>
                        <h4 className="font-semibold">{user.displayName}</h4>
                        <p className="text-sm text-muted-foreground">
                            @{user.handle}
                        </p>
                        <p className="mt-1 text-sm">{user.bio}</p>
                    </div>
                </div>
            </HoverCardContent>
        </HoverCard>
    );
}
```

## API Reference

### `<HoverCard>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | _uncontrolled_ | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state. |
| `onOpenChange` | `(open: boolean) => void` | _none_ | Fires on open/close transitions. |
| `openDelay` | `number` | `700` | Delay (ms) before opening on hover. |
| `closeDelay` | `number` | `300` | Delay (ms) before closing on hover-out. |

### `<HoverCardContent>`

Same positional props as `<PopoverContent>` (`side`, `align`, `sideOffset`, `alignOffset`, `avoidCollisions`, `collisionPadding`).

### `<HoverCardTrigger>`, `<HoverCardArrow>`, `<HoverCardPortal>`

Direct re-exports of the Radix sub-components.

## Implementation Notes

- The chassis NEVER assigns a numeric `z-index` — Radix portals handle stacking.
- HoverCard is hover-driven and therefore inappropriate for touch-only UI; consider `<Popover>` (click-driven) for tap-to-open ergonomics.
- `<HoverCardContent>` self-portals via `<HoverCardPortal>` so consumers do not need to compose the portal manually.
- `align="center"` and `sideOffset={4}` are chassis defaults (matching shadcn upstream).