` element.
**Popup Props:**
| Prop | Type | Default | Description |
| :-------- | :---------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: PreviewCard.Popup.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: PreviewCard.Popup.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: PreviewCard.Popup.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
**Popup Data Attributes:**
| Attribute | Type | Description |
| :------------------ | :------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| data-open | - | Present when the preview card is open. |
| data-closed | - | Present when the preview card is closed. |
| data-align | `'start' \| 'center' \| 'end'` | Indicates how the popup is aligned relative to specified side. |
| data-side | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
| data-starting-style | - | Present when the preview card begins animating in. |
| data-ending-style | - | Present when the preview card is animating out. |
### Popup.Props [#popupprops]
Re-export of [Popup](#popup) props.
### Popup.State [#popupstate]
```typescript
type PreviewCardPopupState = {
/** Whether the preview card is currently open. */
open: boolean;
/** The side of the anchor the component is placed on. */
side: Side;
/** The alignment of the component relative to the anchor. */
align: Align;
/** Whether transitions should be skipped. */
instant: 'dismiss' | 'focus' | undefined;
/** The transition status of the component. */
transitionStatus: TransitionStatus;
};
```
### Arrow [#arrow]
Displays an element positioned against the preview card anchor.
Renders a `
` element.
**Arrow Props:**
| Prop | Type | Default | Description |
| :-------- | :---------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: PreviewCard.Arrow.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: PreviewCard.Arrow.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: PreviewCard.Arrow.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
**Arrow Data Attributes:**
| Attribute | Type | Description |
| :-------------- | :------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| data-open | - | Present when the preview card is open. |
| data-closed | - | Present when the preview card is closed. |
| data-uncentered | - | Present when the preview card arrow is uncentered. |
| data-align | `'start' \| 'center' \| 'end'` | Indicates how the popup is aligned relative to specified side. |
| data-side | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
### Arrow\.Props [#arrowprops]
Re-export of [Arrow](#arrow) props.
### Arrow\.State [#arrowstate]
```typescript
type PreviewCardArrowState = {
/** Whether the preview card is currently open. */
open: boolean;
/** The side of the anchor the component is placed on. */
side: Side;
/** The alignment of the component relative to the anchor. */
align: Align;
/** Whether the arrow cannot be centered on the anchor. */
uncentered: boolean;
};
```
### Viewport [#viewport]
A viewport for displaying content transitions.
This component is only required if one popup can be opened by multiple triggers, its content
changes based on the trigger, and switching between them is animated.
Renders a `
` element.
**Viewport Props:**
| Prop | Type | Default | Description |
| :-------- | :------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactNode` | - | The content to render inside the transition container. |
| className | `string \| ((state: PreviewCard.Viewport.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: PreviewCard.Viewport.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: PreviewCard.Viewport.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
**Viewport Data Attributes:**
| Attribute | Type | Description |
| :------------------------ | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data-activation-direction | `` `${'left' \| 'right' \| ''} ${'down' \| 'up' \| ''}` `` | Indicates the direction from which the popup was activated.
This can be used to create directional animations based on how the popup was triggered.
Contains space-separated values for both horizontal and vertical axes. |
| data-current | - | Applied to the direct child of the viewport when no transitions are present or the new content when it's entering. |
| data-instant | `'dismiss' \| 'focus'` | Present if animations should be instant. |
| data-previous | - | Applied to the direct child of the viewport that contains the exiting content when transitions are present. |
| data-transitioning | - | Indicates that the viewport is currently transitioning between old and new content. |
**Viewport CSS Variables:**
| Variable | Type | Description |
| :--------------- | :--- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--popup-height` | \`\` | The height of the parent popup.
This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered.
It can be used to freeze the dimensions of the popup when animating between different content. |
| `--popup-width` | \`\` | The width of the parent popup.
This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered.
It can be used to freeze the dimensions of the popup when animating between different content. |
### Viewport.Props [#viewportprops]
Re-export of [Viewport](#viewport) props.
### Viewport.State [#viewportstate]
```typescript
type PreviewCardViewportState = {
/** The activation direction of the transitioned content. */
activationDirection: string | undefined;
/** Whether the viewport is currently transitioning between contents. */
transitioning: boolean;
/** Present if animations should be instant. */
instant: 'dismiss' | 'focus' | undefined;
};
```
### createHandle [#createhandle]
Creates a new handle to connect a PreviewCard.Root with detached PreviewCard.Trigger components.
**Return Value:**
```tsx
type ReturnValue = PreviewCard.Handle
;
```
### Handle [#handle]
Controls a PreviewCard imperatively and associates detached `PreviewCard.Trigger` components with
a `PreviewCard.Root`. Create one with `PreviewCard.createHandle()` and pass it to the `handle`
prop of the root and of any triggers rendered outside of it.
The imperative methods take effect only while a root using this handle is mounted; calls made
before a root attaches (or after it unmounts) are ignored.
**Properties:**
| Property | Type | Modifiers | Description |
| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------------- |
| isOpen | `boolean` | readonly | Whether the preview card is currently open. Returns `false` while no root is attached to the handle. |
**Methods:**
```typescript
function open(triggerId: string): void;
```
Opens the preview card and associates it with the trigger with the given id.
This method should only be called in an event handler or an effect (not during rendering).
```typescript
function close(): void;
```
Closes the preview card.
This method should only be called in an event handler or an effect (not during rendering).
## External Types [#external-types]
### PayloadChildRenderFunction [#payloadchildrenderfunction]
```typescript
type PayloadChildRenderFunction = (arg: { payload: unknown | undefined }) => ReactNode;
```
### preventUnmountOnClose [#preventunmountonclose]
```typescript
type preventUnmountOnClose = () => void;
```
### Side [#side]
```typescript
type Side = 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
```
### Align [#align]
```typescript
type Align = 'start' | 'center' | 'end';
```
### OffsetFunction [#offsetfunction]
```typescript
type OffsetFunction = (data: {
side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
align: 'start' | 'center' | 'end';
anchor: { width: number; height: number };
positioner: { width: number; height: number };
}) => number;
```
## Export Groups [#export-groups]
* `PreviewCard.Root`: `PreviewCard.Root`, `PreviewCard.Root.State`, `PreviewCard.Root.Props`, `PreviewCard.Root.Actions`, `PreviewCard.Root.ChangeEventReason`, `PreviewCard.Root.ChangeEventDetails`
* `PreviewCard.Portal`: `PreviewCard.Portal`, `PreviewCard.Portal.State`, `PreviewCard.Portal.Props`
* `PreviewCard.Trigger`: `PreviewCard.Trigger`, `PreviewCard.Trigger.State`, `PreviewCard.Trigger.Props`
* `PreviewCard.Positioner`: `PreviewCard.Positioner`, `PreviewCard.Positioner.State`, `PreviewCard.Positioner.Props`
* `PreviewCard.Popup`: `PreviewCard.Popup`, `PreviewCard.Popup.State`, `PreviewCard.Popup.Props`
* `PreviewCard.Arrow`: `PreviewCard.Arrow`, `PreviewCard.Arrow.State`, `PreviewCard.Arrow.Props`
* `PreviewCard.Backdrop`: `PreviewCard.Backdrop`, `PreviewCard.Backdrop.State`, `PreviewCard.Backdrop.Props`
* `PreviewCard.Viewport`: `PreviewCard.Viewport`, `PreviewCard.Viewport.Props`, `PreviewCard.Viewport.State`
* `PreviewCard.createHandle`
* `PreviewCard.Handle`
* `Default`: `PreviewCardRootState`, `PreviewCardRootProps`, `PreviewCardRootActions`, `PreviewCardRootChangeEventReason`, `PreviewCardRootChangeEventDetails`, `PreviewCardTriggerState`, `PreviewCardTriggerProps`, `PreviewCardPortalState`, `PreviewCardPortalProps`, `PreviewCardPositionerState`, `PreviewCardPositionerProps`, `PreviewCardPopupState`, `PreviewCardPopupProps`, `PreviewCardArrowState`, `PreviewCardArrowProps`, `PreviewCardViewportState`, `PreviewCardViewportProps`, `PreviewCardBackdropState`, `PreviewCardBackdropProps`
## Canonical Types [#canonical-types]
Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.
* `PreviewCard.Root.State`: `PreviewCardRootState`
* `PreviewCard.Root.Props`: `PreviewCardRootProps`
* `PreviewCard.Root.Actions`: `PreviewCardRootActions`
* `PreviewCard.Root.ChangeEventReason`: `PreviewCardRootChangeEventReason`
* `PreviewCard.Root.ChangeEventDetails`: `PreviewCardRootChangeEventDetails`
* `PreviewCard.Portal.State`: `PreviewCardPortalState`
* `PreviewCard.Portal.Props`: `PreviewCardPortalProps`
* `PreviewCard.Trigger.State`: `PreviewCardTriggerState`
* `PreviewCard.Trigger.Props`: `PreviewCardTriggerProps`
* `PreviewCard.Positioner.State`: `PreviewCardPositionerState`
* `PreviewCard.Positioner.Props`: `PreviewCardPositionerProps`
* `PreviewCard.Popup.State`: `PreviewCardPopupState`
* `PreviewCard.Popup.Props`: `PreviewCardPopupProps`
* `PreviewCard.Arrow.State`: `PreviewCardArrowState`
* `PreviewCard.Arrow.Props`: `PreviewCardArrowProps`
* `PreviewCard.Backdrop.State`: `PreviewCardBackdropState`
* `PreviewCard.Backdrop.Props`: `PreviewCardBackdropProps`
* `PreviewCard.Viewport.Props`: `PreviewCardViewportProps`
* `PreviewCard.Viewport.State`: `PreviewCardViewportState`