---
examples:
 - name: basic
   label: Basic Dialog
   description: A modal dialog.
---
A `lightning-dialog` component creates a modal dialog, which displays in a layer above the app
and keeps focus until you close the dialog.

This component inherits styling from
[modals](https://www.lightningdesignsystem.com/components/modals/) in the
Lightning Design System.

Use the `header` attribute to specify text for a header at the top of the dialog; if no
value - or an empty value - is provided for the `header` property, no header area will be displayed.

Specify content for the bottom of the dialog in a `footer` slot. Typically the footer would contain
buttons with actions.

The body of the dialog can contain other components or HTML.

The component supports two methods:
- `showModal` to show a modal dialog
- `close` to close the dialog

Here is a simple dialog example that creates a prompt for the user. It includes a header and
footer content that consists of two buttons.  A button below the dialog shows
how to invoke the dialog.

```html
    <template>
        <lightning-dialog header="Confirmation">
            Are you sure you want to leave the page?
            <div slot="footer">
               <button class="slds-button slds-button_brand" onclick={handleCancelClick}>Cancel</button>
               <button class="slds-button slds-button_brand" onclick={handleLeaveClick}>Leave</button>
            </div>
        </lightning-dialog>
        <button class="slds-button" onclick={openModalDialog}>Open Modal Dialog</button>
    </template>
```

The JavaScript file defines the button actions using the `showModal` and `close` methods.

```js
    export default class LightningDialogDemo extends LightningElement {
        openModalDialog() {
            this.dialog.showModal();
        }
        handleCancelClick() {
            this.dialog.close();
        }
        handleLeaveClick() {
            this.dialog.close();
            // perform the user requested action here after closing the dialog
        }
        get dialog() {
            return this.template.querySelector('lightning-dialog');
        }
    }
```


When you close a modal, it dispatches a `close` event that you can listen to. In addition to any close button
you might implement, modal dialogs have two other ways to close the dialog: pressing the Escape key and clicking
the close (X) icon. In both cases, the component dispatches the `cancel` and `close` events. The `cancel` event
tells you that the user wants to close the dialog, and the `close` event tells you that the dialog is closing.

To prevent the dialog from closing, call `event.preventDefault()` on the `cancel` event. You might use this to
bring attention to unsaved changes, for example, and give the user a chance to save them.

#### Accessibility

When a modal dialog opens, focus goes to the first visible element that participates in Tab key navigation and isn't
disabled. This element has a tabIndex of `0` and is not contained in a Lightning web component that has tabIndex of `-1`.
If no such element is found, focus goes to the close (X) icon.

When a modal dialog closes, the focus returns to the element that was in focus before the dialog opened.
If no such element is found, document.body is focused.


