# Dialog

A window overlaid on either the primary window or another dialog window. Content behind a modal dialog is inert, meaning that users cannot interact with it.

## Import

```
Copyts
import { Dialog } from "@kobalte/core/dialog";
// or
import { Root, Trigger, ... } from "@kobalte/core/dialog";
// or (deprecated)
import { Dialog } from "@kobalte/core";
```

```
Copyts
import { Dialog } from "@kobalte/core/dialog";
// or
import { Root, Trigger, ... } from "@kobalte/core/dialog";
// or (deprecated)
import { Dialog } from "@kobalte/core";
```

## Features

- Follows the [WAI ARIA Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/) design pattern.
- Supports modal and non-modal modes.
- Provides screen reader announcements via rendered title and description.
- Focus is trapped and scrolling is blocked while it is open.
- Pressing `Esc` closes the dialog.
- Can be controlled or uncontrolled.

## Anatomy

The dialog consists of:

- **Dialog:** Contains all the parts of a dialog.
- **Dialog.Trigger:** The button that opens the dialog.
- **Dialog.Portal:** Portals its children into the `body` when the dialog is open.
- **Dialog.Overlay:** The layer that covers the inert portion of the view when the dialog is open.
- **Dialog.Content:** Contains the content to be rendered when the dialog is open.
- **Dialog.CloseButton:** The button that closes the dialog.
- **Dialog.Title:** An accessible title to be announced when the dialog is opened.
- **Dialog.Description:** An optional accessible description to be announced when the dialog is opened.

```
Copytsx
<Dialog>
	<Dialog.Trigger />
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content>
			<Dialog.CloseButton />
			<Dialog.Title />
			<Dialog.Description />
		</Dialog.Content>
	</Dialog.Portal>
</Dialog>
```

```
Copytsx
<Dialog>
	<Dialog.Trigger />
	<Dialog.Portal>
		<Dialog.Overlay />
		<Dialog.Content>
			<Dialog.CloseButton />
			<Dialog.Title />
			<Dialog.Description />
		</Dialog.Content>
	</Dialog.Portal>
</Dialog>
```

## Example

Open

index.tsxstyle.css

```
Copytsx
import { Dialog } from "@kobalte/core/dialog";
import { CrossIcon } from "some-icon-library";
import "./style.css";

function App() {
  return (
    <Dialog>
      <Dialog.Trigger class="dialog__trigger">Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay class="dialog__overlay" />
        <div class="dialog__positioner">
          <Dialog.Content class="dialog__content">
            <div class="dialog__header">
              <Dialog.Title class="dialog__title">About Kobalte</Dialog.Title>
              <Dialog.CloseButton class="dialog__close-button">
                <CrossIcon />
              </Dialog.CloseButton>
            </div>
            <Dialog.Description class="dialog__description">
              Kobalte is a UI toolkit for building accessible web apps and design systems with
              SolidJS. It provides a set of low-level UI components and primitives which can be the
              foundation for your design system implementation.
            </Dialog.Description>
          </Dialog.Content>
        </div>
      </Dialog.Portal>
    </Dialog>
  );
}
```

```
Copytsx
import { Dialog } from "@kobalte/core/dialog";
import { CrossIcon } from "some-icon-library";
import "./style.css";

function App() {
  return (
    <Dialog>
      <Dialog.Trigger class="dialog__trigger">Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay class="dialog__overlay" />
        <div class="dialog__positioner">
          <Dialog.Content class="dialog__content">
            <div class="dialog__header">
              <Dialog.Title class="dialog__title">About Kobalte</Dialog.Title>
              <Dialog.CloseButton class="dialog__close-button">
                <CrossIcon />
              </Dialog.CloseButton>
            </div>
            <Dialog.Description class="dialog__description">
              Kobalte is a UI toolkit for building accessible web apps and design systems with
              SolidJS. It provides a set of low-level UI components and primitives which can be the
              foundation for your design system implementation.
            </Dialog.Description>
          </Dialog.Content>
        </div>
      </Dialog.Portal>
    </Dialog>
  );
}
```

## Usage

### Default open

An initial, uncontrolled open value can be provided using the `defaultOpen` prop.

```
Copytsx
<Dialog defaultOpen>...</Dialog>
```

```
Copytsx
<Dialog defaultOpen>...</Dialog>
```

### Controlled open

The `open` prop can be used to make the open state controlled. The `onOpenChange` event is fired when the user presses the trigger, close button or overlay, and receives the new value.

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [open, setOpen] = createSignal(false);

	return (
		<Dialog open={open()} onOpenChange={setOpen}>
			...
		</Dialog>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [open, setOpen] = createSignal(false);

	return (
		<Dialog open={open()} onOpenChange={setOpen}>
			...
		</Dialog>
	);
}
```

## API Reference

### Dialog

`Dialog` is equivalent to the `Root` import from `@kobalte/core/dialog` (and deprecated `Dialog.Root`).

| Prop | Description |
| --- | --- |
| open | `boolean`<br> The controlled open state of the dialog. |
| defaultOpen | `boolean`<br> The default open state when initially rendered. Useful when you do not need to control the open state. |
| onOpenChange | `(open: boolean) => void`<br> Event handler called when the open state of the dialog changes. |
| id | `string`<br> A unique identifier for the component. The id is used to generate id attributes for nested components. If no id prop is provided, a generated id will be used. |
| modal | `boolean`<br> Whether the dialog should be the only visible content for screen readers, when set to `true`: <br> \- interaction with outside elements will be disabled. <br> \- scroll will be locked. <br> \- focus will be locked inside the dialog content. <br> \- elements outside the dialog content will not be visible for screen readers. |
| preventScroll | `boolean`<br> Whether the scroll should be locked even if the dialog is not modal. |
| forceMount | `boolean`<br> Used to force mounting the dialog (portal, overlay and content) when more control is needed. Useful when controlling animation with SolidJS animation libraries. |
| translations | [`DialogIntlTranslations`](https://github.com/kobaltedev/kobalte/blob/main/packages/core/src/dialog/dialog.intl.ts)<br> Localization strings. |

### Dialog.Trigger

`Dialog.Trigger` consists of [Button](https://kobalte.dev/docs/core/components/button).

| Data attribute | Description |
| --- | --- |
| data-expanded | Present when the dialog is open. |
| data-closed | Present when the dialog is close. |

`Dialog.Content` and `Dialog.Overlay` shares the same data-attributes.

### Dialog.Content

| Prop | Description |
| --- | --- |
| onOpenAutoFocus | `(event: Event) => void`<br> Event handler called when focus moves into the component after opening. It can be prevented by calling `event.preventDefault`. |
| onCloseAutoFocus | `(event: Event) => void`<br> Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. |
| onEscapeKeyDown | `(event: KeyboardEvent) => void`<br> Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
| onPointerDownOutside | `(event: PointerDownOutsideEvent) => void`<br> Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
| onFocusOutside | `(event: FocusOutsideEvent) => void`<br> Event handler called when the focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
| onInteractOutside | `(event: InteractOutsideEvent) => void`<br> Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `Dialog` | none |
| `Dialog.Trigger` | `button` |
| `Dialog.Portal` | `Portal` |
| `Dialog.Overlay` | `div` |
| `Dialog.Content` | `div` |
| `Dialog.CloseButton` | `button` |
| `Dialog.Title` | `h2` |
| `Dialog.Description` | `p` |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `Space` | When focus is on the trigger, opens/closes the dialog. |
| `Enter` | When focus is on the trigger, opens/closes the dialog. |
| `Tab` | Moves focus to the next focusable element. |
| `Shift` \+ `Tab` | Moves focus to the previous focusable element. |
| `Esc` | Closes the dialog and moves focus to the trigger. |

Previous[←Context Menu](https://kobalte.dev/docs/core/components/context-menu)Next[Dropdown Menu→](https://kobalte.dev/docs/core/components/dropdown-menu)