Dialog Tutorial - Using the Dialog Element

Understanding HTML Dialogs

The HTML <dialog> element represents an interactive dialog box that can display messages, forms, confirmations, settings, and other content above the normal page interface.

Dialogs can be displayed as regular non-modal dialogs or as modal dialogs that temporarily require the user to interact with the dialog before returning to the rest of the page.

The <dialog> Element

The <dialog> element provides a native HTML container for content that should appear as a dialog or temporary interactive window.

<dialog>
  <h2>Example Dialog</h2>
  <p>This content appears inside a dialog box.</p>
</dialog>

A dialog is hidden by default. It must be opened before users can see and interact with its content.

Opening a Dialog

JavaScript can open a non-modal dialog with the show() method.

const dialog = document.querySelector('dialog');

dialog.show();

A non-modal dialog appears on the page while allowing users to continue interacting with content outside the dialog.

The showModal() method opens a dialog as a modal. While the modal is open, content outside the dialog becomes inactive until the dialog is closed.

const dialog = document.querySelector('dialog');

dialog.showModal();

Modal dialogs are useful when users need to make a decision, complete an action, or acknowledge information before continuing with the rest of the page.

Closing a Dialog

The close() method closes an open dialog.

const dialog = document.querySelector('dialog');

dialog.close();

A dialog should provide a clear way for users to close it, such as a Cancel, Close, or Done button.

The open Attribute

The boolean open attribute indicates that a dialog is currently displayed.

<dialog open>
  <h2>Open Dialog</h2>
  <p>This dialog is displayed when the page loads.</p>
</dialog>

Although the attribute can make a dialog visible directly in HTML, JavaScript methods such as show() and showModal() are normally used when the dialog needs interactive opening behavior.

Forms in Dialogs

A form inside a dialog can use method="dialog" when its purpose is to close the dialog and return a selected value rather than submit information to a server.

<dialog id="example-dialog">
  <form method="dialog">
    <p>Do you want to continue?</p>
    <button value="cancel">Cancel</button>
    <button value="continue">Continue</button>
  </form>
</dialog>

Activating one of these buttons closes the dialog, and the button's value can be used as the dialog's return value.

The Dialog Backdrop

When a dialog is opened with showModal(), browsers create a backdrop behind it. CSS can style this backdrop with the ::backdrop pseudo-element.

dialog::backdrop {
  background: rgba(0, 0, 0, 0.5);
}

The backdrop visually separates the modal dialog from the inactive page content behind it.

Dialog Accessibility

Native dialogs provide browser-managed behavior that is difficult to reproduce correctly with generic elements. Modal dialogs opened with showModal() are treated as modal interface elements and receive browser-managed focus behavior.

Give dialogs a clear heading, provide understandable controls, and make sure users have an obvious way to close the dialog. Avoid opening dialogs unexpectedly when the user has not performed an action that reasonably calls for one.

HTML Dialog Example

The following example uses a button to open a modal dialog and another button to close it. Experiment by changing showModal() to show() and compare how interaction with the rest of the page changes.

Play in Editor

Dialog Best Practices

Use <dialog> for temporary interactive content that behaves like a dialog window.
Use showModal() when users should complete or dismiss the dialog before interacting with the rest of the page.
Use show() when the dialog should remain non-modal.
Provide a clear heading that identifies the dialog's purpose.
Always provide an understandable way to close or dismiss the dialog.
Use method="dialog" for simple dialog forms that return a choice without submitting data to a server.
Avoid displaying modal dialogs unnecessarily or unexpectedly.
Use CSS for presentation while relying on the native element for its dialog behavior.

Summary

The HTML <dialog> element provides a native way to create dialogs and modal windows. JavaScript can display dialogs with show() or showModal() and close them with close().

Dialogs can contain regular HTML content, forms, buttons, and other interactive elements. Using the native element provides meaningful structure and built-in browser behavior without recreating an entire dialog system from generic elements.

HTML Dialogs