# Dialog Component

Dialogs are used to display crucial information during a user's workflow.

In addition to using this component directly, mdui also provides four functions: [`mdui.dialog`](/en/docs/2/functions/dialog), [`mdui.alert`](/en/docs/2/functions/alert), [`mdui.confirm`](/en/docs/2/functions/confirm), [`mdui.prompt`](/en/docs/2/functions/prompt). These functions provide a more convenient way to use the dialog component.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/dialog.js';
```

Import the TypeScript type:

```ts
import type { Dialog } from 'mdui/components/dialog.js';
```

Example:

```html
<mdui-dialog class="example-dialog">
  Dialog
  <mdui-button>Close</mdui-button>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-dialog");
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector("mdui-button");

  openButton.addEventListener("click", () => dialog.open = true);
  closeButton.addEventListener("click", () => dialog.open = false);
</script>
```

## Examples {#examples}

### Close on Overlay Click {#example-close-on-overlay-click}

Add the `close-on-overlay-click` attribute to close the dialog when the overlay is clicked.

```html
<mdui-dialog close-on-overlay-click class="example-overlay">Dialog</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-overlay");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

### Close on ESC {#example-close-on-esc}

Add the `close-on-esc` attribute to enable closing the dialog when the ESC key is pressed.

```html
<mdui-dialog
  close-on-esc
  close-on-overlay-click
  class="example-ecs"
>Dialog</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-ecs");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

### Fullscreen {#example-fullscreen}

Add the `fullscreen` attribute to make the dialog fullscreen.

```html
<mdui-dialog fullscreen class="example-fullscreen">
  Dialog
  <mdui-button>Close</mdui-button>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-fullscreen");
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector("mdui-button");

  openButton.addEventListener("click", () => dialog.open = true);
  closeButton.addEventListener("click", () => dialog.open = false);
</script>
```

### Icon {#example-icon}

Set the `icon` attribute to add a Material Icon above the dialog.

```html
<mdui-dialog
  icon="restart_alt"
  close-on-overlay-click
  class="example-icon"
>Dialog</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-icon");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

Alternatively, add an icon element above the dialog using the `icon` slot.

```html
<mdui-dialog close-on-overlay-click class="example-icon-slot">
  Dialog
  <mdui-icon slot="icon" name="restart_alt"></mdui-icon>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-icon-slot");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

### Title and Description {#example-headline}

Use the `headline` and `description` attributes to set the dialog's title and description.

```html
<mdui-dialog
  headline="Delete selected images?"
  description="Images will be permanently removed from your account and all synced devices."
  close-on-overlay-click
  class="example-headline"
></mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-headline");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

Alternatively, use the `headline` and `description` slots to set the title and description elements.

```html
<mdui-dialog close-on-overlay-click class="example-headline-slot">
  <span slot="headline">Delete selected images?</span>
  <span slot="description">Images will be permanently removed from your account and all synced devices.</span>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-headline-slot");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

### Action Buttons at the Bottom {#example-action}

Use the `action` slot to add action buttons at the bottom of the dialog.

```html
<mdui-dialog
  close-on-overlay-click
  headline="Delete selected images?"
  class="example-action"
>
  <mdui-button slot="action" variant="text">Cancel</mdui-button>
  <mdui-button slot="action" variant="tonal">Delete</mdui-button>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-action");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

Add the `stacked-actions` attribute to stack the action buttons vertically.

```html
<mdui-dialog
  stacked-actions
  close-on-overlay-click
  headline="Use location service?"
  class="example-stacked-actions"
>
  <mdui-button slot="action" variant="text">Turn on speed boost</mdui-button>
  <mdui-button slot="action" variant="text">No thanks</mdui-button>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-stacked-actions");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

### Top Content {#example-header}

Use the `header` slot to set the top content of the dialog.

```html
<mdui-dialog close-on-overlay-click class="example-header">
  <mdui-top-app-bar slot="header">
    <mdui-button-icon icon="close"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <mdui-button variant="text">Save</mdui-button>
  </mdui-top-app-bar>
  <div style="height: 100px"></div>
</mdui-dialog>

<mdui-button>Open Dialog</mdui-button>

<script>
  const dialog = document.querySelector(".example-header");
  const openButton = dialog.nextElementSibling;

  openButton.addEventListener("click", () => dialog.open = true);
</script>
```

## mdui-dialog API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the Material Icons name for the top icon. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>headline</td>
    <td>headline</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the dialog title. Alternatively, use <code>slot=&quot;headline&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td>description</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The text displayed below the title. Alternatively, use <code>slot=&quot;description&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>open</td>
    <td>open</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Opens the dialog.</p>
</td>
  </tr>
  <tr>
    <td>fullscreen</td>
    <td>fullscreen</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Displays the dialog in full-screen mode.</p>
</td>
  </tr>
  <tr>
    <td>close-on-esc</td>
    <td>closeOnEsc</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Closes the dialog when the ESC key is pressed.</p>
</td>
  </tr>
  <tr>
    <td>close-on-overlay-click</td>
    <td>closeOnOverlayClick</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Closes the dialog when the overlay is clicked.</p>
</td>
  </tr>
  <tr>
    <td>stacked-actions</td>
    <td>stackedActions</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Stacks the bottom action buttons vertically.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>open</td>
    <td><p>Emitted when the dialog starts to open. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>opened</td>
    <td><p>Emitted after the dialog has opened and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>close</td>
    <td><p>Emitted when the dialog starts to close. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>closed</td>
    <td><p>Emitted after the dialog has closed and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>overlay-click</td>
    <td><p>Emitted when the overlay is clicked.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>header</td>
    <td><p>Header area; contains the <code>icon</code> and <code>headline</code> slots by default.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Top icon.</p>
</td>
  </tr>
  <tr>
    <td>headline</td>
    <td><p>Top headline.</p>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td><p>Text below the title.</p>
</td>
  </tr>
  <tr>
    <td>(default)</td>
    <td><p>Main content of the dialog.</p>
</td>
  </tr>
  <tr>
    <td>action</td>
    <td><p>Elements in the bottom action bar.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>overlay</td>
    <td><p>Overlay layer.</p>
</td>
  </tr>
  <tr>
    <td>panel</td>
    <td><p>Dialog container.</p>
</td>
  </tr>
  <tr>
    <td>header</td>
    <td><p>Dialog header, includes icon and headline.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Top icon in header.</p>
</td>
  </tr>
  <tr>
    <td>headline</td>
    <td><p>Top headline in header.</p>
</td>
  </tr>
  <tr>
    <td>body</td>
    <td><p>Dialog body.</p>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td><p>Subtext in body.</p>
</td>
  </tr>
  <tr>
    <td>action</td>
    <td><p>Bottom action buttons.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
  <tr>
    <td>--z-index</td>
    <td><p>The CSS <code>z-index</code> value of the component.</p>
</td>
  </tr>
</tbody>
</table>