On this page

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

Use the Astro primitive adapter to render Popover anatomy with the Runtime wiring included.

---
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>

Use the React primitive adapter when Popover state participates in React rendering.

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>
  );
}

Render the Popover data-sw-* contract yourself, then initialize createPopover.

<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>

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.

Default element: div
Discovery hook: data-sw-popover
Role: -

Props

Prop Type Default

open boolean -

Description

Controls whether Popover is open.

Kind

control

Targets

root

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

defaultOpen boolean false

Description

Sets whether Popover starts open.

Kind

control

Targets

root

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

closeOnEscape boolean true

Description: Closes Popover when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

Description: Closes Popover when the user interacts outside it.
Kind: option
Targets: -
Full type: boolean

modal boolean false

Description: Makes Popover behave as a modal overlay.
Kind: option
Targets: -
Full type: boolean

openOnHover boolean false

Description: Configures the open on hover option for the Root part.
Kind: option
Targets: -
Full type: boolean

closeDelay number 200

Description: Sets how long Popover waits before closing.
Kind: option
Targets: root
Full type: number

onCloseComplete (open: boolean, details: PopoverCloseCompleteDetails) => void -

Description: Runs after Popover has finished closing.
Kind: callback
Targets: -
Full type: (open: boolean, details: PopoverCloseCompleteDetails) => void

onOpenChange (open: boolean, details: PopoverOpenChangeDetails) => void -

Description

Runs when Popover opens or closes.

Kind

callback

Targets

Full type

(open: boolean, details: PopoverOpenChangeDetails) => void

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

Events

Event Callback Value

openChange onOpenChange open: boolean

Description

Fires when Popover opens or closes.

DOM event

starwind:open-change

Details type

PopoverOpenChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

closeComplete onCloseComplete open: boolean

Description: Fires after Popover has finished closing.
DOM event: starwind:close-complete
Details type: PopoverCloseCompleteDetails
Timing: after-state-commit
Cancelable: No

State

State Type Props

open boolean open / defaultOpen

Description

Tracks whether Popover is open.

Initial attribute

data-default-open

Runtime getter

getOpen

Runtime setter

setOpen

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-default-open - Reflects the default open prop on the Root part.

data-close-on-escape - Reflects the close on escape prop on the Root part.

data-close-on-outside-interact - Reflects the close on outside interact prop on the Root part.

data-modal - Reflects the modal prop on the Root part.

data-open-on-hover - Reflects the open on hover prop on the Root part.

data-close-delay - Reflects the close delay prop on the Root part.

Trigger

The control that opens, closes, or targets the Popover content.

Default element: button
Discovery hook: data-sw-popover-trigger
Role: -

Props

Prop Type Default

asChild boolean -

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Metadata

Attribute Value Description

data-as-child - Reflects the as child prop on the Trigger part.

Portal

Moves Popover overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-popover-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

Positions the Popover content relative to its trigger.

Default element: div
Discovery hook: data-sw-popover-positioner
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Popover content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "center"

Description: Sets how Popover content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Popover content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Popover content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

collisionStrategy "initial-placement" | "best-fit" "initial-placement"

Description: Configures the collision strategy option for the Positioner part.
Kind: option
Targets: positioner, popup
Full type: "initial-placement" | "best-fit"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-positioner - Marks the Positioner part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Positioner part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Positioner part.

data-align - Reflects the align prop on the Positioner part.

data-side-offset - Reflects the side offset prop on the Positioner part.

data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

data-collision-strategy - Reflects the collision strategy prop on the Positioner part.

The floating content container for Popover.

Default element: div
Discovery hook: data-sw-popover-popup
Role: dialog

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Popover content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "center"

Description: Sets how Popover content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Popover content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Popover content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

collisionStrategy "initial-placement" | "best-fit" "initial-placement"

Description: Configures the collision strategy option for the Popup part.
Kind: option
Targets: positioner, popup
Full type: "initial-placement" | "best-fit"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

data-align - Reflects the align prop on the Popup part.

data-side-offset - Reflects the side offset prop on the Popup part.

data-avoid-collisions - Reflects the avoid collisions prop on the Popup part.

data-collision-strategy - Reflects the collision strategy prop on the Popup part.

Arrow

The arrow element that visually points to the trigger.

Default element: div
Discovery hook: data-sw-popover-arrow
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-arrow - Marks the Arrow part so Starwind Runtime can find it.

Backdrop

The backdrop shown behind the Popover overlay.

Default element: div
Discovery hook: data-sw-popover-backdrop
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-backdrop - Marks the Backdrop part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Backdrop part.

Title

The accessible title for Popover.

Default element: h2
Discovery hook: data-sw-popover-title
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-title - Marks the Title part so Starwind Runtime can find it.

Description

Supporting description text for Popover.

Default element: p
Discovery hook: data-sw-popover-description
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-description - Marks the Description part so Starwind Runtime can find it.

Close

A control that closes Popover.

Default element: button
Discovery hook: data-sw-popover-close
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-close - Marks the Close part so Starwind Runtime can find it.

Viewport

The visible viewport for Popover content.

Default element: div
Discovery hook: data-sw-popover-viewport
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-popover-viewport - Marks the Viewport part so Starwind Runtime can find it.

Runtime API

Factory: createPopover
Import: @starwind-ui/runtime/popover
Root hook: root data-sw-popover
Option props: closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover

Option Lifecycles

Option	Lifecycle
closeOnEscape	constructor-only
closeOnOutsideInteract	constructor-only
defaultOpen	constructor-only
modal	constructor-only
onCloseComplete	constructor-only
onOpenChange	constructor-only
open	setter-backed
openOnHover	constructor-only

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Popover from Runtime code.

Component Relationship

Popover Direct primitive

Changelog

View version history v1.0.0 5 releases

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.

Layer Metadata

Popover Primitive uses createPopover. Styled components: Popover.

primitive Popover Primitive Popover Primitive uses createPopover. Styled components: Popover. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters popover Popover Presence Floating Overlay Overlays that combine open state, portal structure, and floating placement. /docs/primitives/popover/ createPopover @starwind-ui/runtime/popover /docs/runtime/#create-popover root closeOnEscape closeOnOutsideInteract defaultOpen modal onCloseComplete onOpenChange open openOnHover raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Popover data-sw-* contract yourself, then initialize createPopover. html Use the Astro primitive adapter to render Popover anatomy with the Runtime wiring included. Use the React primitive adapter when Popover state participates in React rendering. tsx div data-sw-popover boolean Controls whether Popover is open. Sets whether Popover starts open. Closes Popover when Escape is pressed. Closes Popover when the user interacts outside it. Makes Popover behave as a modal overlay. Configures the open on hover option for the Root part. closeDelay number Sets how long Popover waits before closing. (open: boolean, details: PopoverCloseCompleteDetails) => void PopoverCloseCompleteDetails Runs after Popover has finished closing. (open: boolean, details: PopoverOpenChangeDetails) => void PopoverOpenChangeDetails Runs when Popover opens or closes. 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 Reflects the close on escape prop on the Root part. data-close-on-outside-interact Reflects the close on outside interact prop on the Root part. data-modal Reflects the modal prop on the Root part. data-open-on-hover Reflects the open on hover prop on the Root part. data-close-delay Reflects the close delay prop on the Root part. data-state state Reflects the current state on the Root part. getOpen setOpen openChange starwind:open-change closeComplete starwind:close-complete trigger button data-sw-popover-trigger asChild Merges behavior onto your child element instead of rendering the default Trigger element. Marks the Trigger part so Starwind Runtime can find it. data-as-child Reflects the as child prop on the Trigger part. Reflects the current state on the Trigger part. portal data-sw-popover-portal Marks the Portal part so Starwind Runtime can find it. positioner data-sw-popover-positioner side "top" | "right" | "bottom" | "left" Sets the preferred side for Popover content. align "start" | "center" | "end" Sets how Popover content aligns to its trigger. sideOffset Sets the distance between Popover content and its trigger. avoidCollisions Allows Popover content to shift or flip to stay visible. collisionStrategy "initial-placement" | "best-fit" Configures the collision strategy option for the Positioner part. Marks the Positioner part so Starwind Runtime can find it. Reflects the current state on the Positioner part. data-side Reflects the side prop on the Positioner part. data-align Reflects the align prop on the Positioner part. data-side-offset Reflects the side offset prop on the Positioner part. data-avoid-collisions Reflects the avoid collisions prop on the Positioner part. data-collision-strategy Reflects the collision strategy prop on the Positioner part. popup data-sw-popover-popup dialog Configures the collision strategy option for the Popup part. Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. Reflects the side prop on the Popup part. Reflects the align prop on the Popup part. Reflects the side offset prop on the Popup part. Reflects the avoid collisions prop on the Popup part. Reflects the collision strategy prop on the Popup part. arrow data-sw-popover-arrow Marks the Arrow part so Starwind Runtime can find it. backdrop data-sw-popover-backdrop Marks the Backdrop part so Starwind Runtime can find it. Reflects the current state on the Backdrop part. title h2 data-sw-popover-title Marks the Title part so Starwind Runtime can find it. description p data-sw-popover-description Marks the Description part so Starwind Runtime can find it. close data-sw-popover-close Marks the Close part so Starwind Runtime can find it. viewport data-sw-popover-viewport Marks the Viewport part so Starwind Runtime can find it. Root Trigger type aria-haspopup aria-expanded Portal Positioner Popup role tabindex tabIndex hidden Arrow Backdrop Title Description Close Viewport @starwind-ui/astro @starwind-ui/astro/popover Render static closed popover anatomy and self-initialize; runtime owns nesting, focus, portal movement, and floating updates. @starwind-ui/react @starwind-ui/react/popover Bridge controlled open state through setOpen, pass close completion through the factory, and clone asChild triggers while keeping latest callback refs. /docs/components/popover/ Direct primitive direct-primitive Styled component Popover

Popover Primitive

Anatomy

Floating Behavior

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Metadata

Portal

Data Attributes

Runtime hooks

Positioner

Props

Data Attributes

Runtime hooks

State

Metadata

Popup

Props

Data Attributes

Runtime hooks

State

Metadata

Arrow

Data Attributes

Runtime hooks

Backdrop

Data Attributes

Runtime hooks

State

Title

Data Attributes

Runtime hooks

Description

Data Attributes

Runtime hooks

Close

Data Attributes

Runtime hooks

Viewport

Data Attributes

Runtime hooks

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.3

v0.1.2

v0.1.1

v0.1.0