# Dialog (/cloud/headless/dialog)



{/* Generated by scripts/sync-base-ui-reference.mjs. Edit the script, not this file. */}

## In Nyte [#in-nyte]

```ts title="Import"
import { Dialog } from "@nyte-ai/ui/dialog";
```

`@nyte-ai/ui/dialog` re-exports the Base UI namespace unchanged. There is no Nyte styling on
this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the
interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

* `desktop/src/renderer/src/chrome/about-dialog.tsx`
* `desktop/src/renderer/src/chrome/open-workspace.tsx`
* `desktop/src/renderer/src/conversation/image-preview.tsx`

The rest of this page is Base UI's documentation for `@base-ui/react/dialog`, reproduced
verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI
package; in Nyte, import from the subpath above.

## Usage guidelines [#usage-guidelines]

* **Dialog doesn't support gestures:** Use [Drawer](/react/components/drawer) when you need gesture support or snap points. A panel that slides in from the edge of the screen and doesn't need gesture support is a positioned Dialog.

## Anatomy [#anatomy]

Import the component and assemble its parts:

```jsx title="Anatomy"
import { Dialog } from '@base-ui/react/dialog';

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Viewport>
      <Dialog.Popup>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
      </Dialog.Popup>
    </Dialog.Viewport>
  </Dialog.Portal>
</Dialog.Root>;
```

## Examples [#examples]

### State [#state]

By default, Dialog is an uncontrolled component that manages its own state.

```tsx title="Uncontrolled dialog"
<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Popup>
      <Dialog.Title>Example dialog</Dialog.Title>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
```

Use `open` and `onOpenChange` props if you need to access or control the state of the dialog.
For example, you can control the dialog state in order to open it imperatively from another place in your app.

```tsx title="Controlled dialog"
const [open, setOpen] = React.useState(false);
return (
  <Dialog.Root open={open} onOpenChange={setOpen}>
    <Dialog.Trigger>Open</Dialog.Trigger>
    <Dialog.Portal>
      <Dialog.Popup>
        <form
          // Close the dialog once the form data is submitted
          onSubmit={async () => {
            await submitData();
            setOpen(false);
          }}
        >
          ...
        </form>
      </Dialog.Popup>
    </Dialog.Portal>
  </Dialog.Root>
);
```

It's also common to use `onOpenChange` if your app needs to do something when the dialog is closed or opened. This is recommended over `React.useEffect` when reacting to state changes.

```tsx title="Running code when dialog state changes"
<Dialog.Root
  open={open}
  onOpenChange={(open) => {
    // Do stuff when the dialog is closed
    if (!open) {
      doStuff();
    }
    // Set the new state
    setOpen(open);
  }}
>
```

### Open from a menu [#open-from-a-menu]

In order to open a dialog using a menu, control the dialog state and open it imperatively using the `onClick` handler on the menu item.

### Nested dialogs [#nested-dialogs]

You can nest dialogs within one another normally.

Use the `[data-nested-dialog-open]` selector and the `var(--nested-dialogs)` CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won't be rendered so that you can present the parent dialog in a clean way behind the one on top of it.

### Close confirmation [#close-confirmation]

This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

To implement this, both dialogs should be controlled. The confirmation dialog may be opened when `onOpenChange` callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.

### Custom focus management [#custom-focus-management]

You can control where the focus goes when the dialog opens and closes using the `initialFocus` and `finalFocus` props on the `<Dialog.Popup>` component.

You can also set these props to `false` to prevent focus from moving when the dialog opens or closes, or to a function that returns the element to focus based on the interaction type.

### Outside scroll dialog [#outside-scroll-dialog]

The dialog can be made scrollable by using `<Dialog.Viewport>` as an outer scrollable container for `<Dialog.Popup>` while the popup can extend past the bottom edge. The scrollable area uses the [Scroll Area component](/react/components/scroll-area) to provide custom scrollbars.

### Inside scroll dialog [#inside-scroll-dialog]

The dialog can be made scrollable by making an inner container scrollable while the popup stays fully on screen. `<Dialog.Viewport>` is used as a positioning container for `<Dialog.Popup>`, while an inner scrollable area is created using the [Scroll Area component](/react/components/scroll-area).

### Placing elements outside the popup [#placing-elements-outside-the-popup]

When adding elements that should appear "outside" the colored popup area, continue to place them inside `<Dialog.Popup>`, but create a child element that has the popup styles. This ensures they are kept in the tab order and announced correctly by screen readers.

`<Dialog.Popup>` has `pointer-events: none`, while inner content (the colored popup and close button) has `pointer-events: auto` so clicks on the backdrop continue to be registered.

### Detached triggers [#detached-triggers]

A dialog can be controlled by a trigger located either inside or outside the `<Dialog.Root>` component.
For simple, one-off interactions, place the `<Dialog.Trigger>` inside `<Dialog.Root>`, as shown in the example at the top of this page.

However, if defining the dialog's content next to its trigger is not practical, you can use a detached trigger.
This involves placing the `<Dialog.Trigger>` outside of `<Dialog.Root>` and linking them with a `handle` created by the `Dialog.createHandle()` function.

The imperative methods on the handle, such as `open()` and `openWithPayload()`, require a `<Dialog.Root>` using the same handle to be mounted.
Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

```jsx title="Detached triggers"
const demoDialog = Dialog.createHandle();

// @highlight
// @highlight-text "handle={demoDialog}"
<Dialog.Trigger handle={demoDialog}>Open</Dialog.Trigger> {/* @highlight-text "handle={demoDialog}" */}

// @highlight
// @highlight-text "handle={demoDialog}"
<Dialog.Root handle={demoDialog}>
  ...
</Dialog.Root>
```

### Multiple triggers [#multiple-triggers]

A single dialog can be opened by multiple trigger elements.
You can achieve this by using the same `handle` for several detached triggers, or by placing multiple `<Dialog.Trigger>` components inside a single `<Dialog.Root>`.

```jsx title="Multiple triggers within the Root part"
<Dialog.Root>
  <Dialog.Trigger>Trigger 1</Dialog.Trigger>
  <Dialog.Trigger>Trigger 2</Dialog.Trigger>
  ...
</Dialog.Root>
```

```jsx title="Multiple detached triggers"
const demoDialog = Dialog.createHandle();

<Dialog.Trigger handle={demoDialog}>Trigger 1</Dialog.Trigger>
<Dialog.Trigger handle={demoDialog}>Trigger 2</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
  ...
</Dialog.Root>
```

The dialog can render different content depending on which trigger opened it.
This is achieved by passing a `payload` to the `<Dialog.Trigger>` and using the function-as-a-child pattern in `<Dialog.Root>`.

The payload can be strongly typed by providing a type argument to the `createHandle()` function:

```jsx title="Detached triggers with payload"
// @highlight
const demoDialog = Dialog.createHandle<{ text: string }>();

// @highlight
// @highlight-text "payload"
<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 1' }}>
  Trigger 1
</Dialog.Trigger>

// @highlight
// @highlight-text "payload"
<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 2' }}>
  Trigger 2
</Dialog.Trigger>

<Dialog.Root handle={demoDialog}>
  {({ payload }) => ( // @highlight-text "payload"
    <Dialog.Portal>
      <Dialog.Popup>
        <Dialog.Title>Dialog</Dialog.Title>
        {payload !== undefined && ( // @highlight-text "payload"
          <Dialog.Description>
            This has been opened by {payload.text} {/* @highlight-text "payload" */}
          </Dialog.Description>
        )}
      </Dialog.Popup>
    </Dialog.Portal>
  )}
</Dialog.Root>
```

### Controlled mode with multiple triggers [#controlled-mode-with-multiple-triggers]

You can control the dialog's open state externally using the `open` and `onOpenChange` props on `<Dialog.Root>`.
This allows you to manage the dialog's visibility based on your application's state.
When using multiple triggers, you have to manage which trigger is active with the `triggerId` prop on `<Dialog.Root>` and the `id` prop on each `<Dialog.Trigger>`.

Note that there is no separate `onTriggerIdChange` prop.
Instead, the `onOpenChange` callback receives an additional argument, `eventDetails`, which contains the trigger element that initiated the state change.

## API reference [#api-reference]

### Root [#root]

Groups all parts of the dialog.
Doesn't render its own HTML element.

**Root Props:**

| Prop                    | Type                                                                      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| :---------------------- | :------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultOpen             | `boolean`                                                                 | `false` | Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| open                    | `boolean`                                                                 | -       | Whether the dialog is currently open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| onOpenChange            | `((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)` | -       | Event handler called when the dialog is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| actionsRef              | `React.RefObject<Dialog.Root.Actions \| null>`                            | -       | A ref to imperative actions. `unmount`: Manually unmounts the dialog.&#xA;Call this after any externally controlled closing animation finishes.`close`: Closes the dialog imperatively when called.                                                                                                                                                                                                                                                                                                                                                                                           |
| defaultTriggerId        | `string \| null`                                                          | -       | ID of the trigger that the dialog is associated with.&#xA;This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| disablePointerDismissal | `boolean`                                                                 | `false` | Whether to prevent the dialog from closing on outside presses.&#xA;For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| handle                  | `Dialog.Handle<Payload>`                                                  | -       | A handle to associate the dialog with a trigger.&#xA;If specified, allows external triggers to control the dialog's open state.&#xA;Can be created with the Dialog.createHandle() method.                                                                                                                                                                                                                                                                                                                                                                                                     |
| modal                   | `boolean \| 'trap-focus'`                                                 | `true`  | Determines if the dialog enters a modal state when open. `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed.`'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so&#xA;touch screen readers can escape the popup. |
| onOpenChangeComplete    | `((open: boolean) => void)`                                               | -       | Event handler called after any animations complete when the dialog is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| triggerId               | `string \| null`                                                          | -       | ID of the trigger that the dialog is associated with.&#xA;This is useful in conjunction with the `open` prop to create a controlled dialog.&#xA;There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).                                                                                                                                                                                                                                                                                                                              |
| children                | `React.ReactNode \| PayloadChildRenderFunction<Payload>`                  | -       | The content of the dialog.&#xA;This can be a regular React node or a render function that receives the `payload` of the active trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### Root.Props [#rootprops]

Re-export of [Root](#root) props.

### Root.State [#rootstate]

```typescript
type DialogRootState = {};
```

### Root.Actions [#rootactions]

```typescript
type DialogRootActions = { unmount: () => void; close: () => void };
```

### Root.ChangeEventReason [#rootchangeeventreason]

```typescript
type DialogRootChangeEventReason =
  | 'trigger-press'
  | 'outside-press'
  | 'escape-key'
  | 'close-press'
  | 'focus-out'
  | 'imperative-action'
  | 'none';
```

### Root.ChangeEventDetails [#rootchangeeventdetails]

```typescript
type DialogRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};
```

### Trigger [#trigger]

A button that opens the dialog.
Renders a `<button>` element.

**Trigger Props:**

| Prop         | Type                                                                                         | Default | Description                                                                                                                                                                                             |
| :----------- | :------------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| handle       | `Dialog.Handle<Payload>`                                                                     | -       | A handle to associate the trigger with a dialog.&#xA;Can be created with the Dialog.createHandle() method.                                                                                              |
| nativeButton | `boolean`                                                                                    | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).               |
| payload      | `Payload`                                                                                    | -       | A payload to pass to the dialog when it is opened.                                                                                                                                                      |
| id           | `string`                                                                                     | -       | ID of the trigger. In addition to being forwarded to the rendered element,&#xA;it is also used to specify the active trigger for the dialog in controlled mode (with the Dialog.Root `triggerId` prop). |
| className    | `string \| ((state: Dialog.Trigger.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                                |
| style        | `React.CSSProperties \| ((state: Dialog.Trigger.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                             |
| render       | `ReactElement \| ((props: HTMLProps, state: Dialog.Trigger.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.           |

**Trigger Data Attributes:**

| Attribute       | Type | Description                                    |
| :-------------- | :--- | :--------------------------------------------- |
| data-popup-open | -    | Present when the corresponding dialog is open. |
| data-disabled   | -    | Present when the trigger is disabled.          |

### Trigger.Props [#triggerprops]

Re-export of [Trigger](#trigger) props.

### Trigger.State [#triggerstate]

```typescript
type DialogTriggerState = {
  /** Whether the trigger is currently disabled. */
  disabled: boolean;
  /** Whether the dialog is currently open and was opened by this trigger. */
  open: boolean;
};
```

### Portal [#portal]

A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to `<body>`.
Renders a `<div>` element.

**Portal Props:**

| Prop        | Type                                                                                        | Default | Description                                                                                                                                                                                   |
| :---------- | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| container   | `HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`   | -       | A parent element to render the portal element into.                                                                                                                                           |
| className   | `string \| ((state: Dialog.Portal.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style       | `React.CSSProperties \| ((state: Dialog.Portal.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| keepMounted | `boolean`                                                                                   | `false` | Whether to keep the portal mounted in the DOM while the popup is hidden.                                                                                                                      |
| render      | `ReactElement \| ((props: HTMLProps, state: Dialog.Portal.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### Portal.Props [#portalprops]

Re-export of [Portal](#portal) props.

### Portal.State [#portalstate]

```typescript
type DialogPortalState = {};
```

### Backdrop [#backdrop]

An overlay displayed beneath the popup.
Renders a `<div>` element.

**Backdrop Props:**

| Prop        | Type                                                                                          | Default | Description                                                                                                                                                                                   |
| :---------- | :-------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| forceRender | `boolean`                                                                                     | `false` | Whether the backdrop is forced to render even when nested.                                                                                                                                    |
| className   | `string \| ((state: Dialog.Backdrop.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style       | `React.CSSProperties \| ((state: Dialog.Backdrop.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render      | `ReactElement \| ((props: HTMLProps, state: Dialog.Backdrop.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Backdrop Data Attributes:**

| Attribute           | Type | Description                                  |
| :------------------ | :--- | :------------------------------------------- |
| data-open           | -    | Present when the dialog is open.             |
| data-closed         | -    | Present when the dialog is closed.           |
| data-starting-style | -    | Present when the dialog begins animating in. |
| data-ending-style   | -    | Present when the dialog is animating out.    |

### Backdrop.Props [#backdropprops]

Re-export of [Backdrop](#backdrop) props.

### Backdrop.State [#backdropstate]

```typescript
type DialogBackdropState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};
```

### Popup [#popup]

A container for the dialog contents.
Renders a `<div>` element.

**Popup Props:**

| Prop         | Type                                                                                                                          | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| :----------- | :---------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| initialFocus | `boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`  | -       | Determines the element to focus when the dialog is opened.&#xA;By default, focus moves to the first tabbable element inside the popup, except when the dialog&#xA;is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. `false`: Do not move focus.`true`: Move focus based on the default behavior (first tabbable element or popup).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).&#xA;Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| finalFocus   | `boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | -       | Determines the element to focus when the dialog is closed. `false`: Do not move focus.`true`: Move focus based on the default behavior (trigger or previously focused element).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).&#xA;Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.                                                                                                                                                                                               |
| className    | `string \| ((state: Dialog.Popup.State) => string \| undefined)`                                                              | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| style        | `React.CSSProperties \| ((state: Dialog.Popup.State) => React.CSSProperties \| undefined)`                                    | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| render       | `ReactElement \| ((props: HTMLProps, state: Dialog.Popup.State) => ReactElement)`                                             | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**Popup Data Attributes:**

| Attribute               | Type | Description                                                      |
| :---------------------- | :--- | :--------------------------------------------------------------- |
| data-open               | -    | Present when the dialog is open.                                 |
| data-closed             | -    | Present when the dialog is closed.                               |
| data-nested             | -    | Present when the dialog is nested within another dialog.         |
| data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
| data-starting-style     | -    | Present when the dialog begins animating in.                     |
| data-ending-style       | -    | Present when the dialog is animating out.                        |

**Popup CSS Variables:**

| Variable           | Type     | Description                                   |
| :----------------- | :------- | :-------------------------------------------- |
| `--nested-dialogs` | `number` | Indicates how many dialogs are nested within. |

### Popup.Props [#popupprops]

Re-export of [Popup](#popup) props.

### Popup.State [#popupstate]

```typescript
type DialogPopupState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within a parent dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};
```

### Title [#title]

A heading that labels the dialog.
Renders an `<h2>` element.

**Title Props:**

| Prop      | Type                                                                                       | Default | Description                                                                                                                                                                                   |
| :-------- | :----------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Dialog.Title.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Dialog.Title.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: HTMLProps, state: Dialog.Title.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### Title.Props [#titleprops]

Re-export of [Title](#title) props.

### Title.State [#titlestate]

```typescript
type DialogTitleState = {};
```

### Description [#description]

A paragraph with additional information about the dialog.
Renders a `<p>` element.

**Description Props:**

| Prop      | Type                                                                                             | Default | Description                                                                                                                                                                                   |
| :-------- | :----------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Dialog.Description.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Dialog.Description.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: HTMLProps, state: Dialog.Description.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### Description.Props [#descriptionprops]

Re-export of [Description](#description) props.

### Description.State [#descriptionstate]

```typescript
type DialogDescriptionState = {};
```

### Close [#close]

A button that closes the dialog.
Renders a `<button>` element.

**Close Props:**

| Prop         | Type                                                                                       | Default | Description                                                                                                                                                                                   |
| :----------- | :----------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nativeButton | `boolean`                                                                                  | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).     |
| className    | `string \| ((state: Dialog.Close.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style        | `React.CSSProperties \| ((state: Dialog.Close.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render       | `ReactElement \| ((props: HTMLProps, state: Dialog.Close.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Close Data Attributes:**

| Attribute     | Type | Description                          |
| :------------ | :--- | :----------------------------------- |
| data-disabled | -    | Present when the button is disabled. |

### Close.Props [#closeprops]

Re-export of [Close](#close) props.

### Close.State [#closestate]

```typescript
type DialogCloseState = {
  /** Whether the button is currently disabled. */
  disabled: boolean;
};
```

### Viewport [#viewport]

A positioning container for the dialog popup that can be made scrollable.
Renders a `<div>` element.

**Viewport Props:**

| Prop      | Type                                                                                          | Default | Description                                                                                                                                                                                   |
| :-------- | :-------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Dialog.Viewport.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Dialog.Viewport.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: HTMLProps, state: Dialog.Viewport.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Viewport Data Attributes:**

| Attribute               | Type | Description                                                      |
| :---------------------- | :--- | :--------------------------------------------------------------- |
| data-open               | -    | Present when the dialog is open.                                 |
| data-closed             | -    | Present when the dialog is closed.                               |
| data-nested             | -    | Present when the dialog is nested within another dialog.         |
| data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
| data-starting-style     | -    | Present when the dialog begins animating in.                     |
| data-ending-style       | -    | Present when the dialog is animating out.                        |

### Viewport.Props [#viewportprops]

Re-export of [Viewport](#viewport) props.

### Viewport.State [#viewportstate]

```typescript
type DialogViewportState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within another dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};
```

### createHandle [#createhandle]

Creates a new handle to connect a Dialog.Root with detached Dialog.Trigger components.

**Return Value:**

```tsx
type ReturnValue = Dialog.Handle<Payload>;
```

### Handle [#handle]

Controls a Dialog imperatively and associates detached `Dialog.Trigger` components with a
`Dialog.Root`. Create one with `Dialog.createHandle()` and pass it to the `handle` prop of the
root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made
before a root attaches (or after it unmounts) are ignored.

**Properties:**

| Property | Type      | Modifiers | Description                                                                                    |
| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------- |
| isOpen   | `boolean` | readonly  | Whether the dialog is currently open. Returns `false` while no root is attached to the handle. |

**Methods:**

```typescript
function open(triggerId: string | null): void;
```

Opens the dialog, optionally associating it with a trigger.

This method should only be called in an event handler or an effect (not during rendering).

```typescript
function openWithPayload(payload: Payload): void;
```

Opens the dialog with the given payload, without associating it with any trigger.

This method should only be called in an event handler or an effect (not during rendering).

```typescript
function close(): void;
```

Closes the dialog.

This method should only be called in an event handler or an effect (not during rendering).

## External Types [#external-types]

### InteractionType [#interactiontype]

```typescript
type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';
```

### PayloadChildRenderFunction [#payloadchildrenderfunction]

```typescript
type PayloadChildRenderFunction = (arg: { payload: unknown | undefined }) => ReactNode;
```

### preventUnmountOnClose [#preventunmountonclose]

```typescript
type preventUnmountOnClose = () => void;
```

## Export Groups [#export-groups]

* `Dialog.Backdrop`: `Dialog.Backdrop`, `Dialog.Backdrop.Props`, `Dialog.Backdrop.State`
* `Dialog.Close`: `Dialog.Close`, `Dialog.Close.Props`, `Dialog.Close.State`
* `Dialog.Description`: `Dialog.Description`, `Dialog.Description.Props`, `Dialog.Description.State`
* `Dialog.Popup`: `Dialog.Popup`, `Dialog.Popup.Props`, `Dialog.Popup.State`
* `Dialog.Portal`: `Dialog.Portal`, `Dialog.Portal.State`, `Dialog.Portal.Props`
* `Dialog.Root`: `Dialog.Root`, `Dialog.Root.State`, `Dialog.Root.Props`, `Dialog.Root.Actions`, `Dialog.Root.ChangeEventReason`, `Dialog.Root.ChangeEventDetails`
* `Dialog.Viewport`: `Dialog.Viewport`, `Dialog.Viewport.State`, `Dialog.Viewport.Props`
* `Dialog.Title`: `Dialog.Title`, `Dialog.Title.Props`, `Dialog.Title.State`
* `Dialog.Trigger`: `Dialog.Trigger`, `Dialog.Trigger.Props`, `Dialog.Trigger.State`
* `Dialog.createHandle`
* `Dialog.Handle`
* `Default`: `DialogRootState`, `DialogRootProps`, `DialogRootActions`, `DialogRootChangeEventReason`, `DialogRootChangeEventDetails`, `DialogTriggerProps`, `DialogTriggerState`, `DialogPortalState`, `DialogPortalProps`, `DialogPopupProps`, `DialogPopupState`, `DialogBackdropProps`, `DialogBackdropState`, `DialogTitleProps`, `DialogTitleState`, `DialogDescriptionProps`, `DialogDescriptionState`, `DialogCloseProps`, `DialogCloseState`, `DialogViewportState`, `DialogViewportProps`

## Canonical Types [#canonical-types]

Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.

* `Dialog.Backdrop.Props`: `DialogBackdropProps`
* `Dialog.Backdrop.State`: `DialogBackdropState`
* `Dialog.Close.Props`: `DialogCloseProps`
* `Dialog.Close.State`: `DialogCloseState`
* `Dialog.Description.Props`: `DialogDescriptionProps`
* `Dialog.Description.State`: `DialogDescriptionState`
* `Dialog.Popup.Props`: `DialogPopupProps`
* `Dialog.Popup.State`: `DialogPopupState`
* `Dialog.Portal.State`: `DialogPortalState`
* `Dialog.Portal.Props`: `DialogPortalProps`
* `Dialog.Root.State`: `DialogRootState`
* `Dialog.Root.Props`: `DialogRootProps`
* `Dialog.Root.Actions`: `DialogRootActions`
* `Dialog.Root.ChangeEventReason`: `DialogRootChangeEventReason`
* `Dialog.Root.ChangeEventDetails`: `DialogRootChangeEventDetails`
* `Dialog.Viewport.State`: `DialogViewportState`
* `Dialog.Viewport.Props`: `DialogViewportProps`
* `Dialog.Title.Props`: `DialogTitleProps`
* `Dialog.Title.State`: `DialogTitleState`
* `Dialog.Trigger.Props`: `DialogTriggerProps`
* `Dialog.Trigger.State`: `DialogTriggerState`