On this page

Dialog Primitive

Dialog is a Starwind Runtime primitive in the dialog-native-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 Dialog anatomy with the Runtime wiring included.

---
import { Dialog } from "@starwind-ui/astro/dialog";
---

<Dialog.Root>
  <Dialog.Trigger>Open dialog</Dialog.Trigger>
  <Dialog.Backdrop />
  <Dialog.Popup>
    <Dialog.Title>Dialog title</Dialog.Title>
    <Dialog.Description>Dialog description</Dialog.Description>
    <Dialog.Close>Close</Dialog.Close>
  </Dialog.Popup>
</Dialog.Root>

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

import { Dialog } from "@starwind-ui/react/dialog";

export function Example() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open dialog</Dialog.Trigger>
      <Dialog.Backdrop />
      <Dialog.Popup>
        <Dialog.Title>Dialog title</Dialog.Title>
        <Dialog.Description>Dialog description</Dialog.Description>
        <Dialog.Close>Close</Dialog.Close>
      </Dialog.Popup>
    </Dialog.Root>
  );
}

Render the Dialog data-sw-* contract yourself, then initialize createDialog.

<div data-sw-dialog>
  <button data-sw-dialog-trigger type="button" aria-haspopup="dialog">Open dialog</button>
  <div data-sw-dialog-overlay hidden></div>
  <dialog data-sw-dialog-content role="dialog">
    <h2 data-sw-dialog-title>Dialog title</h2>
    <p data-sw-dialog-description>Dialog description</p>
    <button data-sw-dialog-close type="button">Close</button>
  </dialog>
</div>

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

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

API Reference

Root

The main element that owns the Dialog Runtime instance.

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

Props

Prop Type Default

open boolean -

Description

Controls whether Dialog 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 Dialog 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 Dialog when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

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

modal boolean true

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

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

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

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

Description

Runs when Dialog opens or closes.

Kind

callback

Targets

Full type

(open: boolean, details: DialogOpenChangeDetails) => 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 Dialog opens or closes.

DOM event

starwind:open-change

Details type

DialogOpenChangeDetails

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 Dialog has finished closing.
DOM event: starwind:close-complete
Details type: DialogCloseCompleteDetails
Timing: after-state-commit
Cancelable: No

State

State Type Props

open boolean open / defaultOpen

Description

Tracks whether Dialog 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-dialog - 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.

Trigger

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

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

Props

Prop Type Default

targetId string -

Description: Targets a specific root element by id.
Kind: attribute
Targets: trigger
Full type: string

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dialog-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-sw-dialog-target-id - Reflects the sw dialog target id prop on the Trigger part.

Backdrop

The backdrop shown behind the Dialog overlay.

Default element: div
Discovery hook: data-sw-dialog-overlay
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dialog-overlay - Marks the Backdrop part so Starwind Runtime can find it.

State

Attribute Value Description

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

The floating content container for Dialog.

Default element: dialog
Discovery hook: data-sw-dialog-content
Role: dialog

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-dialog-content - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

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

Title

The accessible title for Dialog.

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

Data Attributes

Runtime hooks

Attribute Value Description

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

Description

Supporting description text for Dialog.

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

Data Attributes

Runtime hooks

Attribute Value Description

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

Close

A control that closes Dialog.

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

Data Attributes

Runtime hooks

Attribute Value Description

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

Runtime API

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

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

Runtime Setters

Method Target Description

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

Component Relationship

Dialog Direct primitive

Changelog

View version history v1.0.0 3 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.1

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

Introduced modal and non-modal open state, focus management, dismissal, presence, and nested-dialog coordination.

Layer Metadata

Dialog Primitive uses createDialog. Styled components: Dialog.

primitive Dialog Primitive Dialog Primitive uses createDialog. Styled components: Dialog. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters dialog Dialog Dialog Native Overlay Native dialog-backed overlays with runtime-owned dismissal and presence. /docs/primitives/dialog/ createDialog @starwind-ui/runtime/dialog /docs/runtime/#create-dialog root closeOnEscape closeOnOutsideInteract defaultOpen modal onCloseComplete onOpenChange open raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Dialog data-sw-* contract yourself, then initialize createDialog. html Use the Astro primitive adapter to render Dialog anatomy with the Runtime wiring included. Use the React primitive adapter when Dialog state participates in React rendering. tsx div data-sw-dialog boolean Controls whether Dialog is open. Sets whether Dialog starts open. Closes Dialog when Escape is pressed. Closes Dialog when the user interacts outside it. Makes Dialog behave as a modal overlay. (open: boolean, details: DialogCloseCompleteDetails) => void DialogCloseCompleteDetails Runs after Dialog has finished closing. (open: boolean, details: DialogOpenChangeDetails) => void DialogOpenChangeDetails Runs when Dialog 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-state state Reflects the current state on the Root part. getOpen setOpen openChange starwind:open-change closeComplete starwind:close-complete trigger button data-sw-dialog-trigger targetId string Targets a specific root element by id. Marks the Trigger part so Starwind Runtime can find it. data-sw-dialog-target-id Reflects the sw dialog target id prop on the Trigger part. Reflects the current state on the Trigger part. backdrop data-sw-dialog-overlay Marks the Backdrop part so Starwind Runtime can find it. Reflects the current state on the Backdrop part. popup data-sw-dialog-content Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. title h2 data-sw-dialog-title Marks the Title part so Starwind Runtime can find it. description p data-sw-dialog-description Marks the Description part so Starwind Runtime can find it. close data-sw-dialog-close Marks the Close part so Starwind Runtime can find it. Root Trigger type aria-haspopup Backdrop hidden Popup Title Description Close @starwind-ui/astro @starwind-ui/astro/dialog Render static native-dialog anatomy and self-initialize; runtime owns focus, body scroll lock, nested dialog state, and animated close completion. @starwind-ui/react @starwind-ui/react/dialog Bridge controlled open state through setOpen, subscribe to openChange for callbacks, pass close completion through the factory, and recreate on constructor-only option changes. /docs/components/dialog/ Direct primitive direct-primitive Styled component Dialog

Dialog Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Metadata

Backdrop

Data Attributes

Runtime hooks

State

Popup

Data Attributes

Runtime hooks

State

Title

Data Attributes

Runtime hooks

Description

Data Attributes

Runtime hooks

Close

Data Attributes

Runtime hooks

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0