<dialog> Tag in HTML

Home/Reference/<dialog>

The <dialog> element

The <dialog> tag creates a popup box, such as a confirmation message or a sign-up form. Open it with JavaScript: showModal() shows it as a modal, centered over a dimmed backdrop, with keyboard focus kept inside and the Escape key closing it, while show() opens it without blocking the page. Close it with close().

Last updated: October 3, 2026

Quick facts

CategoryFlow content
Content modelFlow content
Tag omissionNeither the start nor the end tag can be omitted
Permitted parentsAny element that accepts flow content
DOM interfaceHTMLDialogElement

Syntax

<dialog id="box"> <p>Saved!</p> <form method="dialog"><button>OK</button></form> </dialog> <button onclick="box.showModal()">Open</button>

Live example

Edit the code below and watch the preview update instantly.

index.html
Preview
Open in Full Editor →

Attributes

AttributeDescription
openShows the dialog as non-modal. Prefer the show() / showModal() methods instead of setting this yourself
closedbyNewer browsers: any lets clicking the backdrop close it, closerequest allows only Escape, none only script

Methods (JavaScript)

AttributeDescription
showModal()Opens it as a modal: backdrop, focus trapped inside, Escape closes
show()Opens it without blocking the rest of the page
close(value)Closes it; the optional value becomes dialog.returnValue

Common examples

A confirmation dialog

Open it with showModal(); a form with method="dialog" closes it and tells you which button was pressed.

<dialog id="confirm"> <form method="dialog"> <p>Delete this file?</p> <button value="cancel">Cancel</button> <button value="delete">Delete</button> </form> </dialog> <button type="button" id="del">Delete file</button> <script> del.addEventListener("click", () => confirm.showModal()); confirm.addEventListener("close", () => console.log(confirm.returnValue)); </script>

Styling the backdrop

The ::backdrop pseudo-element is the dimmed layer behind a modal dialog.

<style> dialog { border: none; border-radius: 12px; padding: 1.5rem; max-width: 420px; } dialog::backdrop { background: rgba(0, 0, 0, 0.6); } </style>

A newsletter sign-up popup

Give the dialog a heading and a clear close button so it’s easy to dismiss.

<dialog id="news" aria-labelledby="news-title"> <h2 id="news-title">Get our weekly tips</h2> <form method="post" action="/subscribe"> <label for="nl-email">Email</label> <input type="email" id="nl-email" name="email" required> <button>Subscribe</button> </form> <button type="button" onclick="news.close()">No thanks</button> </dialog>

<dialog> vs a custom <div> modal

A homemade modal built from a <div> needs a lot of JavaScript to behave properly: trap keyboard focus inside, close on Escape, stop people clicking the page behind, and move focus back afterwards. Miss one and keyboard or screen reader users get stuck.

<dialog> opened with showModal() does all of this by default. It sits on the top layer above everything else, makes the rest of the page inert, closes on Escape and returns focus to the button that opened it. Unless you must support very old browsers, it’s the better choice.

<dialog>Custom <div> modal
Escape key closesBuilt inYou code it
Background made inertBuilt inYou code it
Always on topYes (top layer)Depends on z-index

Common mistakes to avoid

  • Using show() when you need a modal. show() opens it without a backdrop or focus trap; use showModal() for popups that need an answer.
  • Adding the open attribute in HTML for a modal. That shows it as a non-modal dialog; open modals with JavaScript.
  • No visible way to close it. Always include a close or cancel button — not everyone knows about the Escape key.
  • Popups the moment the page loads. Intrusive popups annoy visitors, and Google can rank pages lower on mobile when they cover the content.

Accessibility & SEO tips

  • Give every dialog a heading and connect it with aria-labelledby, so screen readers announce what it’s about.
  • Put the autofocus attribute on the element that should get focus first, such as the first field or the safest button.
  • Avoid covering the main content with popups on mobile right after a visitor arrives from search — it can hurt your rankings.

Browser support

Supported in all modern browsers, including Chrome, Edge, Firefox, Safari and their mobile versions (Safari added it in 2022). Very old browsers display it as a plain box.

Related tags

<details> <form> <button> <template>

Frequently asked questions

What is the difference between showModal() and show()?
showModal() opens the dialog on top of everything with a dimmed backdrop, keeps keyboard focus inside it and lets Escape close it — right for confirmations and forms. show() opens it like a normal box, and the rest of the page stays usable.
How do I close a <dialog> when the backdrop is clicked?
In newer browsers add closedby="any". For wider support, listen for clicks on the dialog itself: if event.target is the dialog element (the backdrop area), call dialog.close().
Can a form close the dialog?
Yes. A <form method="dialog"> inside the dialog closes it when submitted, and the clicked button's value becomes dialog.returnValue — no JavaScript needed for the closing part.
How do I open a <dialog> when the page loads?
Call dialog.showModal() in a script that runs after the dialog exists, for example with defer. Use this sparingly — popups on arrival annoy visitors.
How do I stop the page scrolling while a dialog is open?
Add body:has(dialog[open]) { overflow: hidden; } to your CSS. It locks the page scroll whenever a dialog is open.
How do I get the value of the button that closed a dialog?
Give each button in a method="dialog" form a value. After it closes, read dialog.returnValue in the close event handler.