# 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
### Astro
Use the Astro primitive adapter to render Dialog anatomy with the Runtime wiring included.
```astro
---
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>
```

### React
Use the React primitive adapter when Dialog state participates in React rendering.
```tsx
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>
  );
}
```

### HTML
Render the Dialog data-sw-* contract yourself, then initialize createDialog.
```html
<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>
```

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

<template>
  <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>
</template>
```
## API Reference
### Root
The main element that owns the Dialog Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-dialog` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Dialog 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 Dialog 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 Dialog when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Dialog when the user interacts outside it. | - |
| modal | `boolean` | true | option | Makes Dialog behave as a modal overlay. | - |
| onCloseComplete | `(open: boolean, details: DialogCloseCompleteDetails) => void` | - | callback | Runs after Dialog has finished closing. | - |
| onOpenChange | `(open: boolean, details: DialogOpenChangeDetails) => void` | - | callback | Runs when Dialog 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-dialog` | 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-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 Dialog 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` | DialogOpenChangeDetails | before-state-commit | Yes | Fires when Dialog 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` | DialogCloseCompleteDetails | after-state-commit | No | Fires after Dialog has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Dialog from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-modal`, `data-state` | The dialog root needs default-open, dismissal, modality, 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 Dialog content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-dialog-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| targetId | `string` | - | attribute | Targets a specific root element by id. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-dialog-target-id` | prop | - | Reflects the sw dialog target id prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-trigger`, `type`, `aria-haspopup`, `data-sw-dialog-target-id`, `data-state` | Triggers need button semantics, dialog affordances, and initial closed state before activation listeners attach. |

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

### Popup
The floating content container for Dialog.
| Fact | Value |
| --- | --- |
| Default element | `dialog` |
| Discovery hook | `data-sw-dialog-content` |
| Role | `dialog` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-content` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-content`, `data-state` | The native dialog element starts closed and receives runtime-owned open/close state. |

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

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

### Close
A control that closes Dialog.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-dialog-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-dialog-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-dialog-close`, `type` | Close controls need button semantics before runtime listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDialog`](/docs/runtime/#create-dialog) |
| Import | `@starwind-ui/runtime/dialog` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Dialog](/docs/components/dialog/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/dialog` | `createDialog` |
| Astro Primitive | `@starwind-ui/astro/dialog` | `Dialog`, `DialogRoot`, `DialogTrigger`, `DialogBackdrop`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose` |
| React Primitive | `@starwind-ui/react/dialog` | `Dialog`, `DialogRoot`, `DialogTrigger`, `DialogBackdrop`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Dialog` |
| runtime-factory | `createDialog` |
| part | `Dialog.Root` |
| part | `Dialog.Trigger` |
| part | `Dialog.Backdrop` |
| part | `Dialog.Popup` |
| part | `Dialog.Title` |
| part | `Dialog.Description` |
| part | `Dialog.Close` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### 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.