## 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.
Preview card content is a floating surface. It resolves two surface levels above its parent and uses the matching contextual border and shadow, so it follows the same surface model as `Popover`.
## Usage [#usage]
```tsx
import {
PreviewCard,
PreviewCardContent,
PreviewCardTrigger,
} from "@tilt-legal/cubitt-components/preview-card";
```
```tsx
}>
Jane Smith
Preview content goes here
```
## Examples [#examples]
### Basic [#basic]
Hover over the name to see a preview of user information.
```tsx
import { Button } from "@tilt-legal/cubitt-components/button";
import {
PreviewCard,
PreviewCardContent,
PreviewCardTrigger,
} from "@tilt-legal/cubitt-components/preview-card";
import { MapPin } from "@tilt-legal/cubitt-icons/ui/outline";
}>
John Doe
John Doe
Software Engineer with 5+ years of experience in web development.
San Francisco, CA
;
```
### Positions [#positions]
Preview card positioned on physical and writing-direction-aware sides of the trigger.
```tsx
import { Button } from "@tilt-legal/cubitt-components/button";
import {
PreviewCard,
PreviewCardContent,
PreviewCardTrigger,
} from "@tilt-legal/cubitt-components/preview-card";
}>
Left
Left Position
Preview appears on the left side.
;
```
### With Badges [#with-badges]
Hover to see a richer profile preview with skills and metadata.
```tsx
import { Avatar, AvatarFallback } from "@tilt-legal/cubitt-components/avatar";
import { Badge } from "@tilt-legal/cubitt-components/badge";
import { Button } from "@tilt-legal/cubitt-components/button";
import {
PreviewCard,
PreviewCardContent,
PreviewCardTrigger,
} from "@tilt-legal/cubitt-components/preview-card";
import { Calendar, Suitcase } from "@tilt-legal/cubitt-icons/ui/outline";
}>
Sarah Johnson
SJ
Sarah Johnson
Product Designer
UI/UXFigmaDesign Systems
Tech Corp
Joined March 2023
;
```
## 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, eventDetails) => 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 closing or unmounting the popup. |
| `handle` | `PreviewCard.Handle` | — | Handle used to associate external triggers with the card. |
| `triggerId` | `string \| null` | — | Active trigger id for controlled preview cards. |
| `defaultTriggerId` | `string \| null` | — | Initial active trigger id for uncontrolled preview cards. |
| `children` | `ReactNode \| (payload) => ReactNode` | — | Child elements or payload-driven render function. |
### 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" \| "inline-start" \| "inline-end"` | `"bottom"` | Which side of the trigger to position. |
| `sideOffset` | `number \| function` | `8` | Distance in pixels from the trigger. |
| `alignOffset` | `number \| function` | `0` | Offset in pixels along the alignment axis. |
| `anchor` | `Element \| RefObject \| function` | trigger | Optional custom anchor to position against. |
| `positionMethod` | `"absolute" \| "fixed"` | `"absolute"` | CSS positioning method for the floating layer. |
| `children` | `ReactNode` | — | The content to display inside the preview card. |