

<Preview name="BasicPreviewCardExample" />

## Overview [#overview]

The `PreviewCard` component surfaces glanceable, contextual information when the user hovers over a trigger element. It's designed for supplementary content like user profiles, link destinations, or metadata — information that helps the user decide whether to take further action.

## Usage [#usage]

```tsx
import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from "@tilt-legal/cubitt-components/primitives";
```

```tsx
<PreviewCard>
  <PreviewCardTrigger render={<a href="/profile" />}>
    Jane Smith
  </PreviewCardTrigger>
  <PreviewCardContent>
    <p>Preview content goes here</p>
  </PreviewCardContent>
</PreviewCard>
```

## Examples [#examples]

### Basic [#basic]

Hover over the name to see a preview of user information.

<Preview name="BasicPreviewCardExample" />

### Positions [#positions]

Preview card positioned on different sides of the trigger.

<Preview name="PreviewCardPositionsExample" />

### With Badges [#with-badges]

Hover to see a richer profile preview with skills and metadata.

<Preview name="PreviewCardWithBadgesExample" />

### Link Preview [#link-preview]

Preview card triggered by a text link.

<Preview name="PreviewCardLinkExample" />

## API Reference [#api-reference]

### PreviewCard [#previewcard]

The root component that manages the preview card state.

| Prop                   | Type                      | Default | Description                                                |
| ---------------------- | ------------------------- | ------- | ---------------------------------------------------------- |
| `open`                 | `boolean`                 | —       | Whether the preview card is currently open (controlled).   |
| `defaultOpen`          | `boolean`                 | `false` | Whether the preview card is initially open (uncontrolled). |
| `onOpenChange`         | `(open: boolean) => void` | —       | Callback fired when the preview card is opened or closed.  |
| `onOpenChangeComplete` | `(open: boolean) => void` | —       | Callback fired after any open/close animations complete.   |
| `actionsRef`           | `RefObject`               | —       | Reference to imperative actions for manual unmounting.     |
| `children`             | `ReactNode`               | —       | Child elements of the preview card.                        |

### PreviewCardTrigger [#previewcardtrigger]

The element that shows the preview card when hovered.

| Prop         | Type                                      | Default | Description                                                                    |
| ------------ | ----------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `delay`      | `number`                                  | `0`     | Delay in milliseconds before showing the preview.                              |
| `closeDelay` | `number`                                  | `0`     | Delay in milliseconds before hiding the preview.                               |
| `children`   | `ReactNode`                               | —       | The content of the trigger element.                                            |
| `className`  | `string \| (state) => string`             | —       | CSS classes or function that returns classes based on component state.         |
| `render`     | `ReactElement \| (props) => ReactElement` | —       | Allows composing the trigger with another component. Receives props to spread. |

### PreviewCardContent [#previewcardcontent]

The container for the preview card content, positioned relative to the trigger.

| Prop          | Type                                     | Default    | Description                                     |
| ------------- | ---------------------------------------- | ---------- | ----------------------------------------------- |
| `className`   | `string`                                 | —          | Additional CSS classes for the content.         |
| `align`       | `"start" \| "center" \| "end"`           | `"center"` | Alignment relative to the trigger.              |
| `side`        | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Which side of the trigger to position.          |
| `sideOffset`  | `number`                                 | `8`        | Distance in pixels from the trigger.            |
| `alignOffset` | `number`                                 | `0`        | Offset in pixels along the alignment axis.      |
| `children`    | `ReactNode`                              | —          | The content to display inside the preview card. |