HTML Dialog Element

The HTML <dialog> element creates a native dialog box in the browser. You can use it for confirmations, alerts, quick forms, and small interactive panels that need to open above the page.

A dialog can be modal or non-modal. A modal dialog keeps focus inside the dialog until the user closes it. A non-modal dialog stays open but still allows users to interact with the rest of the page.

HTML Dialog Syntax

Place the content inside the <dialog> tag. Use JavaScript methods to open or close it.

Syntax:

<dialog id="messageBox">
  <p>Your message goes here.</p>
</dialog>

Open a Modal Dialog

Use showModal() when the user must respond before continuing. This method also creates a backdrop behind the dialog.

Example:

const dialog = document.querySelector("#confirmBox");
const openButton = document.querySelector("#openBox");

// Open the dialog as a modal window.
openButton.addEventListener("click", () => {
  dialog.showModal();
});

Close a Dialog

You can close a dialog by calling close(). If you pass a value, it becomes available through the dialog's returnValue property.

Example:

const dialog = document.querySelector("#confirmBox");

// Close the dialog and store the result.
dialog.close("confirmed");

console.log(dialog.returnValue);

Use a Dialog Form

A form with method="dialog" closes its parent dialog when a button is submitted. The button value becomes the dialog return value.

Example:

<dialog id="deleteDialog">
  <form method="dialog">
    <p>Delete this file?</p>
    <button value="cancel">Cancel</button>
    <button value="delete">Delete</button>
  </form>
</dialog>

Style the Backdrop

Use the ::backdrop pseudo-element to style the area behind a modal dialog. This only applies when the dialog is opened with showModal().

Example:

/* Style the overlay behind a modal dialog. */
dialog::backdrop {
  background: rgba(0, 0, 0, 0.55);
}

Runnable Browser Example

This example opens a modal dialog and displays the value returned by the selected button.

Example:

<button id="openDialog">Open Dialog</button>

<dialog id="profileDialog">
  <h2>Confirm Profile Update</h2>
  <p>Rohan changed his email address.</p>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="confirm">Confirm</button>
  </form>
</dialog>

<script>
  const dialog = document.querySelector("#profileDialog");

  // showModal() opens the dialog with a backdrop.
  document.querySelector("#openDialog").onclick = () => {
    dialog.showModal();
  };
</script>

Accessibility Guidelines

• Use clear heading text inside the dialog.
• Keep the dialog short and focused on one action.
• Provide an obvious close or cancel option.
• Use showModal() only when the page should wait for a decision.
• Do not open dialogs unexpectedly when the page loads.

Tip: Prefer the native dialog element for common modal behavior because the browser handles focus and backdrop behavior better than many custom modal scripts.

Conclusion

The HTML <dialog> element gives you a built-in way to create modal and non-modal dialogs. Use showModal(), show(), close(), and method="dialog" to build clear, accessible interactions with less custom code.