How to Use the dialog Element

The HTML dialog element represents a temporary window for a confirmation, input, or settings task. It gives the browser a standard place to handle showing, focus, and closing behavior.

The answer first

Minimal example

<button type="button" id="open-dialog">Open confirmation</button>

<dialog id="confirm-dialog" aria-labelledby="confirm-title">
  <h2 id="confirm-title">Send this form?</h2>
  <p>Review the information before sending it.</p>
  <form method="dialog">
    <button type="submit" value="cancel" autofocus>Cancel</button>
    <button type="submit" value="ok">Send</button>
  </form>
</dialog>

<script>
  const openDialog = document.querySelector('#open-dialog');
  const confirmDialog = document.querySelector('#confirm-dialog');
  openDialog.addEventListener('click', () => confirmDialog.showModal());
</script>

This example opens a modal dialog with showModal() and closes it with buttons in a method="dialog" form. If the application needs to act on the choice, read returnValue after the dialog closes.

Modal and non-modal dialogs

Method or state	What happens	Typical use
showModal()	Modal. The page behind the dialog is not interactive	Confirmation, deletion, or required input
show()	Non-modal. Other parts of the page remain usable	Supporting information or a small parallel task
open	Represents the active state; it does not by itself say whether the dialog is modal	Reading state, while methods manage showing and closing

Use showModal() when people must finish the decision before returning to the page. Simply adding and removing open does not perform all of the modal and closing cleanup that the dialog methods provide.

Provide a title and sensible focus

Give the dialog a heading that explains its purpose and connect it with aria-labelledby. Add autofocus to the input or button that people should use first when the default focus choice is not appropriate.

After a modal closes, the browser attempts to return focus to the control that opened it. Check that focus stays within the dialog while it is open and that keyboard users can close it.

Receive a choice from a form

<form method="dialog"> closes the dialog without making a network request. The submitter's value can be read through dialog.returnValue after the dialog closes.

dialog.addEventListener('close', () => {
  if (dialog.returnValue === 'ok') {
    // Continue after confirmation.
  }
});

Common mistakes

• Using a div as a dialog and recreating focus and Escape-key behavior from scratch.
• Opening a dialog without providing a close action.
• Using show() while expecting a modal dialog that blocks the page behind it.
• Leaving out a title or description, so people cannot tell what they are confirming.
• Putting essential instructions or required actions only inside a closed dialog.

Check it in Atlas

For the open state, the modal top layer and inert background, focus, cancel, close, requestClose(), closedby, form boundaries, browser behavior, and accessibility evidence, see the dialog element in Yugien Atlas.