<dialog>

A dialog or modal window: a confirmation, form, or message shown above the rest of the page.

Display
none (block when open)
Closing tag
Required
Permitted content
Flow content
On this page

Example

#
HTML
<button type="button" id="open-btn">Delete project</button>

<dialog id="confirm" aria-labelledby="confirm-title">
  <h2 id="confirm-title">Delete the “Business card” project?</h2>
  <p>This action can’t be undone.</p>
  <button type="button" id="cancel-btn" autofocus>Cancel</button>
  <button type="button" id="delete-btn">Delete</button>
</dialog>

<script>
  const dialog = document.getElementById('confirm')
  document.getElementById('open-btn').addEventListener('click', () => dialog.showModal())
  document.getElementById('cancel-btn').addEventListener('click', () => dialog.close())
  document.getElementById('delete-btn').addEventListener('click', () => dialog.close())
</script>
Preview

Definition and usage

#

The <dialog> element creates a dialog window. It is hidden by default, and you open it in JavaScript: the showModal() method shows it as a modal above the whole page with a dimmed backdrop, while show() shows it as a regular window that doesn’t block the rest of the page. The close() method closes it.

A modal opened with showModal() does the hard work for you: it moves focus into the window, blocks interaction with the rest of the page, closes on the Escape key, and is placed in a layer above all other elements (the top layer), so you don’t have to fight with z-index. You style the backdrop behind the window with the ::backdrop pseudo-element.

A form with method="dialog" placed inside the window closes it when a button is clicked and stores the button’s value in the returnValue property, so you know what the user chose. Since December 2025 you can also open a dialog without JavaScript, using a button with the commandfor and command="show-modal" attributes.

Syntax

#
Syntax
<dialog id="window">
  …
</dialog>

Attributes

#
  • open

    boolean attribute

    The window is visible. An attribute written in the markup shows the window as non-modal, with no dimming and without blocking the page. To open and close it, use the show(), showModal(), and close() methods instead of adding or removing this attribute yourself.

The element also supports all global attributes, such as class, id, style and hidden.

Attributes in practice

#

open

boolean attribute

The window is visible. An attribute written in the markup shows the window as non-modal, with no dimming and without blocking the page. To open and close it, use the show(), showModal(), and close() methods instead of adding or removing this attribute yourself.

HTML
<dialog open>
  <p>You have an unfinished lesson: <strong>Lists in HTML</strong>.</p>
  <button type="button" onclick="this.closest('dialog').close()">Later</button>
</dialog>
Preview

More examples

#
A form with method="dialog" and returnValue
HTML
<button type="button" id="rate-btn">Rate the lesson</button>
<p id="result"></p>

<dialog id="rate-dialog" aria-labelledby="rate-title">
  <form method="dialog">
    <h2 id="rate-title">How would you rate the lesson?</h2>
    <button value="poor">Poor</button>
    <button value="good">Good</button>
    <button value="great">Great</button>
  </form>
</dialog>

<script>
  const dialog = document.getElementById('rate-dialog')
  const result = document.getElementById('result')
  document.getElementById('rate-btn').addEventListener('click', () => {
    dialog.returnValue = ''
    dialog.showModal()
  })
  dialog.addEventListener('close', () => {
    result.textContent = dialog.returnValue ? 'Your rating: ' + dialog.returnValue : 'Closed without a rating'
  })
</script>
Preview

Every button in a form with method="dialog" closes the window and stores its value in dialog.returnValue. Escape closes the window without changing that value.

Without JavaScript: commandfor and command
HTML
<button type="button" commandfor="quiz-rules" command="show-modal">Quiz rules</button>

<dialog id="quiz-rules" aria-labelledby="quiz-title">
  <h2 id="quiz-title">Quiz rules</h2>
  <p>You have 10 minutes for 5 questions. Each has one correct answer.</p>
  <button type="button" commandfor="quiz-rules" command="close">Got it</button>
</dialog>
Preview

The commandfor and command attributes have worked in all major browsers since December 2025. In older versions the button does nothing.

Default CSS

#

Most browsers display this element with these default styles:

CSS
dialog:not([open]) {
  display: none;
}
dialog {
  position: absolute;
  inset-inline: 0;
  width: fit-content;
  height: fit-content;
  margin: auto;
  border: solid;
  padding: 1em;
  background-color: Canvas;
  color: CanvasText;
}
dialog::backdrop {
  background: rgba(0, 0, 0, 0.1);
}

Browser support

#

Widely available · since 2022

Works in all modern browsers, phones included. You can use it without worry.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • Don’t add the open attribute by hand if you need a modal. Only showModal() blocks the rest of the page and handles the Escape key.
  • Give the window a name with aria-labelledby pointing to its heading, so a screen reader immediately announces what the window is about.
  • When confirming irreversible actions, set autofocus on the safe button, for example “Cancel”.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.