# PreviewCard Primitive

PreviewCard is a Starwind Runtime primitive in the presence-floating-overlay contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render PreviewCard anatomy with the Runtime wiring included.
```astro
---
import { PreviewCard } from "@starwind-ui/astro/preview-card";
---

<PreviewCard.Root>
  <PreviewCard.Trigger>Preview profile</PreviewCard.Trigger>
  <PreviewCard.Positioner>
    <PreviewCard.Popup>
      <PreviewCard.Arrow />
    </PreviewCard.Popup>
  </PreviewCard.Positioner>
</PreviewCard.Root>
```

### React
Use the React primitive adapter when PreviewCard state participates in React rendering.
```tsx
import { PreviewCard } from "@starwind-ui/react/preview-card";

export function Example() {
  return (
    <PreviewCard.Root>
      <PreviewCard.Trigger>Preview profile</PreviewCard.Trigger>
      <PreviewCard.Positioner>
        <PreviewCard.Popup>
          <PreviewCard.Arrow />
        </PreviewCard.Popup>
      </PreviewCard.Positioner>
    </PreviewCard.Root>
  );
}
```

### HTML
Render the PreviewCard data-sw-* contract yourself, then initialize createPreviewCard.
```html
<div data-sw-preview-card>
  <button data-sw-preview-card-trigger type="button">Preview profile</button>
  <div data-sw-preview-card-positioner>
    <div data-sw-preview-card-popup role="tooltip" hidden>
      <div data-sw-preview-card-arrow></div>
    </div>
  </div>
</div>

<script type="module">
  import { createPreviewCard } from "@starwind-ui/runtime/preview-card";

  const root = document.querySelector("[data-sw-preview-card]");
  if (root) {
    createPreviewCard(root);
  }
</script>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the PreviewCard Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether PreviewCard is open. |
| defaultOpen | `boolean` | false | control | Sets whether PreviewCard starts open. |
| closeDelay | `number` | 300 | option | Sets how long PreviewCard waits before closing. |
| closeOnEscape | `boolean` | true | option | Closes PreviewCard when Escape is pressed. |
| closeOnOutsideInteract | `boolean` | true | option | Closes PreviewCard when the user interacts outside it. |
| disableHoverableContent | `boolean` | false | option | Configures the disable hoverable content option for the Root part. |
| openDelay | `number` | 600 | option | Sets how long PreviewCard waits before opening. |
| onOpenChange | `(open: boolean, details: PreviewCardOpenChangeDetails) => void` | - | callback | Runs when PreviewCard opens or closes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-content-hoverable` | prop | - | Reflects the content hoverable prop on the Root part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether PreviewCard is open. | React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | PreviewCardOpenChangeDetails | before-state-commit | Yes | Fires when PreviewCard opens or closes. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes PreviewCard from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card`, `data-default-open`, `data-close-delay`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-content-hoverable`, `data-open-delay`, `data-state` | The preview card root needs timing, dismissal, hoverability, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the PreviewCard content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-preview-card-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. |
| disabled | `boolean` | false | option | Disables the Trigger part. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-as-child` | prop | - | Reflects the as child prop on the Trigger part. |
| `data-close-delay` | prop | - | Reflects the close delay prop on the Trigger part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Trigger part. |
| `data-open-delay` | prop | - | Reflects the open delay prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-trigger`, `data-as-child`, `data-close-delay`, `data-disabled`, `data-open-delay`, `aria-disabled`, `data-state`, `disabled`, `type` | Triggers need delay overrides, disabled state, and initial closed state before pointer/focus listeners attach. |

### Portal
Moves PreviewCard overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the PreviewCard content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for PreviewCard content. |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how PreviewCard content aligns to its trigger. |
| sideOffset | `number` | 0 | option | Sets the distance between PreviewCard content and its trigger. |
| avoidCollisions | `boolean` | true | option | Allows PreviewCard content to shift or flip to stay visible. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Positioner part. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions` | The positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for PreviewCard.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-popup` |
| Role | `tooltip` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for PreviewCard content. |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how PreviewCard content aligns to its trigger. |
| sideOffset | `number` | 0 | option | Sets the distance between PreviewCard content and its trigger. |
| avoidCollisions | `boolean` | true | option | Allows PreviewCard content to shift or flip to stay visible. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-popup`, `role`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `hidden` | The preview card popup starts hidden with tooltip semantics and initial placement hints before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Arrow
The arrow element that visually points to the trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Arrow part. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-arrow`, `data-state` | The optional arrow receives state and placement updates from the floating runtime. |

### Backdrop
The backdrop shown behind the PreviewCard overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-backdrop`, `data-state`, `hidden` | The optional backdrop starts hidden and receives runtime-owned visibility state. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The visible viewport for PreviewCard content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-preview-card-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-preview-card-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Viewport part. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-preview-card-viewport`, `data-state` | The optional viewport receives state and placement updates from the floating runtime. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createPreviewCard`](/docs/runtime/#create-preview-card) |
| Import | `@starwind-ui/runtime/preview-card` |
| Root part | root |
| Option props | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disableHoverableContent, onOpenChange, open, openDelay |
| Option lifecycles | closeDelay: constructor-only, closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, disableHoverableContent: constructor-only, onOpenChange: constructor-only, open: setter-backed, openDelay: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Hover Card](/docs/components/hover-card/) | Renamed Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/preview-card` | `createPreviewCard` |
| Astro Primitive | `@starwind-ui/astro/preview-card` | `PreviewCard`, `PreviewCardRoot`, `PreviewCardTrigger`, `PreviewCardPortal`, `PreviewCardPositioner`, `PreviewCardPopup`, `PreviewCardArrow`, `PreviewCardBackdrop`, `PreviewCardViewport` |
| React Primitive | `@starwind-ui/react/preview-card` | `PreviewCard`, `PreviewCardRoot`, `PreviewCardTrigger`, `PreviewCardPortal`, `PreviewCardPositioner`, `PreviewCardPopup`, `PreviewCardArrow`, `PreviewCardBackdrop`, `PreviewCardViewport` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `PreviewCard` |
| runtime-factory | `createPreviewCard` |
| part | `PreviewCard.Root` |
| part | `PreviewCard.Trigger` |
| part | `PreviewCard.Portal` |
| part | `PreviewCard.Positioner` |
| part | `PreviewCard.Popup` |
| part | `PreviewCard.Arrow` |
| part | `PreviewCard.Backdrop` |
| part | `PreviewCard.Viewport` |