# Popover Primitive

Popover is a Starwind Runtime primitive in the presence-floating-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Popover anatomy with the Runtime wiring included.
```astro
---
import { Popover } from "@starwind-ui/astro/popover";
---

<Popover.Root>
  <Popover.Trigger>Open popover</Popover.Trigger>
  <Popover.Backdrop />
  <Popover.Positioner>
    <Popover.Popup>
      <Popover.Title>Popover title</Popover.Title>
      <Popover.Description>Popover description</Popover.Description>
      <Popover.Close>Close</Popover.Close>
      <Popover.Arrow />
    </Popover.Popup>
  </Popover.Positioner>
</Popover.Root>
```

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

export function Example() {
  return (
    <Popover.Root>
      <Popover.Trigger>Open popover</Popover.Trigger>
      <Popover.Backdrop />
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Popover title</Popover.Title>
          <Popover.Description>Popover description</Popover.Description>
          <Popover.Close>Close</Popover.Close>
          <Popover.Arrow />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Root>
  );
}
```

### HTML
Render the Popover data-sw-* contract yourself, then initialize createPopover.
```html
<div data-sw-popover>
  <button data-sw-popover-trigger type="button" aria-haspopup="dialog">Open popover</button>
  <div data-sw-popover-backdrop hidden></div>
  <div data-sw-popover-positioner>
    <div data-sw-popover-popup role="dialog" tabindex="-1" hidden>
      <h2 data-sw-popover-title>Popover title</h2>
      <p data-sw-popover-description>Popover description</p>
      <button data-sw-popover-close type="button">Close</button>
      <div data-sw-popover-arrow></div>
    </div>
  </div>
</div>

<script type="module">
  import { createPopover } from "@starwind-ui/runtime/popover";

  const root = document.querySelector("[data-sw-popover]");
  if (root) {
    createPopover(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Popover anatomy.
```vue
<script setup lang="ts">
import Popover from "@starwind-ui/vue/popover";
</script>

<template>
  <Popover.Root>
    <Popover.Trigger>Open popover</Popover.Trigger>
    <Popover.Backdrop />
    <Popover.Positioner>
      <Popover.Popup>
        <Popover.Title>Popover title</Popover.Title>
        <Popover.Description>Popover description</Popover.Description>
        <Popover.Close>Close</Popover.Close>
        <Popover.Arrow />
      </Popover.Popup>
    </Popover.Positioner>
  </Popover.Root>
</template>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, avoidCollisions, collisionStrategy |
## API Reference
### Root
The main element that owns the Popover Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Popover is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Popover starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Popover when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Popover when the user interacts outside it. | - |
| modal | `boolean` | false | option | Makes Popover behave as a modal overlay. | - |
| openOnHover | `boolean` | false | option | Configures the open on hover option for the Root part. | - |
| closeDelay | `number` | 200 | option | Sets how long Popover waits before closing. | - |
| onCloseComplete | `(open: boolean, details: PopoverCloseCompleteDetails) => void` | - | callback | Runs after Popover has finished closing. | - |
| onOpenChange | `(open: boolean, details: PopoverOpenChangeDetails) => void` | - | callback | Runs when Popover opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover` | 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-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-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-open-on-hover` | prop | - | Reflects the open on hover prop on the Root part. |
| `data-close-delay` | prop | - | Reflects the close 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 Popover is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | PopoverOpenChangeDetails | before-state-commit | Yes | Fires when Popover opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | PopoverCloseCompleteDetails | after-state-commit | No | Fires after Popover has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Popover from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-open-on-hover`, `data-close-delay`, `data-state` | The popover root needs default-open, dismissal, hover, close-delay, 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 Popover content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-popover-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-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-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-popover-trigger`, `data-as-child`, `aria-haspopup`, `aria-expanded`, `data-state`, `type` | Triggers need dialog affordances, asChild markers, and initial closed state before activation listeners attach. |

### Portal
Moves Popover overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
| `data-container` | prop | - | Reflects the container prop on the Portal part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Portal part. |
| `data-sw-portal-placement` | constant | `runtime` | Identifies Portal metadata for styling and selectors. |
| `data-placement` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Positioner
Positions the Popover content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Popover content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Popover content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Popover content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Popover content to shift or flip to stay visible. | - |
| collisionStrategy | `"initial-placement" \| "best-fit"` | "initial-placement" | option | Configures the collision strategy option for the Positioner part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-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. |
| `data-collision-strategy` | prop | - | Reflects the collision strategy prop on the Positioner part. |
#### Refs
| Part | Public |
| --- | --- |
| positioner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-positioner`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `data-collision-strategy` | The positioner carries initial placement hints used by the shared floating runtime. |

### Popup
The floating content container for Popover.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-popup` |
| Role | `dialog` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Popover content. | - |
| align | `"start" \| "center" \| "end"` | "center" | option | Sets how Popover content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Popover content and its trigger. | - |
| avoidCollisions | `boolean` | true | option | Allows Popover content to shift or flip to stay visible. | - |
| collisionStrategy | `"initial-placement" \| "best-fit"` | "initial-placement" | option | Configures the collision strategy option for the Popup part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-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. |
| `data-collision-strategy` | prop | - | Reflects the collision strategy prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-popup`, `role`, `tabindex`, `data-state`, `data-side`, `data-align`, `data-side-offset`, `data-avoid-collisions`, `data-collision-strategy`, `hidden` | The popup starts hidden with dialog semantics, focus targetability, 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-popover-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-arrow` | runtime | - | Marks the Arrow part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| arrow | Yes |

### Backdrop
The backdrop shown behind the Popover overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-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-popover-backdrop`, `data-state`, `hidden` | The optional backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Title
The accessible title for Popover.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-popover-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Popover.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-popover-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Popover.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-popover-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-popover-close`, `type` | Close controls need button semantics before runtime listeners attach. |

### Viewport
The visible viewport for Popover content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-popover-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-popover-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createPopover`](/docs/runtime/#create-popover) |
| Import | `@starwind-ui/runtime/popover` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed, openOnHover: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Popover](/docs/components/popover/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/popover` | `createPopover` |
| Astro Primitive | `@starwind-ui/astro/popover` | `Popover`, `PopoverRoot`, `PopoverTrigger`, `PopoverPortal`, `PopoverPositioner`, `PopoverPopup`, `PopoverArrow`, `PopoverBackdrop`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`, `PopoverViewport` |
| React Primitive | `@starwind-ui/react/popover` | `Popover`, `PopoverRoot`, `PopoverTrigger`, `PopoverPortal`, `PopoverPositioner`, `PopoverPopup`, `PopoverArrow`, `PopoverBackdrop`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`, `PopoverViewport` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Popover` |
| runtime-factory | `createPopover` |
| part | `Popover.Root` |
| part | `Popover.Trigger` |
| part | `Popover.Portal` |
| part | `Popover.Positioner` |
| part | `Popover.Popup` |
| part | `Popover.Arrow` |
| part | `Popover.Backdrop` |
| part | `Popover.Title` |
| part | `Popover.Description` |
| part | `Popover.Close` |
| part | `Popover.Viewport` |
## Changelog
### v1.1.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.1.0
- Added portable Portal container and disabled controls, with deterministic framework and Runtime placement reporting for nested floating content.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.3
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.2
- Added collision strategy support to the generated Astro and React Primitive adapters for best-fit placement in constrained viewports.
### v0.1.1
- Added modal background-scroll locking when modal behavior is enabled.
### v0.1.0
- Introduced open state, floating placement, focus handling, dismissal, presence, and nesting.