# Dialog Primitive

Dialog is a Starwind Runtime primitive in the dialog-native-overlay contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Dialog is open. |
| defaultOpen | `boolean` | false | control | Sets whether Dialog starts open. |
| 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. |
#### 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 supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change and starwind:close-complete, 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` | DialogOpenChangeDetails | before-state-commit | Yes | Fires when Dialog opens or closes. |
| 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 |
| --- | --- | --- | --- | --- |
| 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` |