HTML Dialog: Browser Support, Features, Known Issues

What is HTML Dialog?

The HTML <dialog> element is an interactive element from the WHATWG HTML Living Standard that shows a dialog box on a web page. It supports a modal mode through showModal(), a non-modal mode through show(), and a close() method, and modal dialogs paint in the top layer with a ::backdrop pseudo-element.

Which browsers does HTML Dialog support?

The HTML <dialog> element works in every modern desktop and mobile browser, but support starts at very different versions across vendors and was disabled by default in Chrome and Firefox for many releases before becoming a stable feature.

What are the key features of HTML Dialog?

The <dialog> element wraps a small set of methods, attributes, events, and CSS hooks that handle modality, dismissal, and styling without any custom JavaScript. The headline features focus on top-layer placement, native dismissal, and form integration.

• showModal() method: Opens the dialog modally, marks the rest of the page inert, and stacks the dialog in the top layer above any z-index. The browser fires a cancel event when the user presses Escape.
• show() method: Opens the dialog non-modally without a backdrop, leaves the rest of the page interactive, and is the right choice for inspector panels and toasts that should not block input.
• close() and returnValue: Closes the dialog, fires the close event, and stores an optional string in dialog.returnValue. Form method="dialog" calls close() automatically with the submitter's value.
• ::backdrop pseudo-element: Paints behind a modal dialog in the top layer. Use it for blur, dim, or fade-in effects, and animate it through the display property when paired with transition-behavior: allow-discrete.
• :modal and :open pseudo-classes: :modal matches a dialog opened by showModal(), and :open matches any open dialog from Chrome 134, Edge 134, Firefox 137, and Safari 17.4 on.
• closedby attribute: Accepts any, closerequest, or none and controls whether clicking the backdrop or pressing Escape closes the dialog. Works in Chrome 134, Edge 134, Firefox 137, and Safari 18.2 on.
• form method="dialog": Closes a parent <dialog> on submit and posts the submitter's value to dialog.returnValue instead of issuing a network request.
• autofocus and inert: Setting autofocus on a child input moves keyboard focus into the dialog on open, and the rest of the page becomes inert automatically when showModal() runs.

What are the known issues with HTML Dialog across browsers?

HTML dialog support is broad now, but a handful of cross-browser quirks still bite teams that ship modals on legacy stacks or rely on the newest attributes. Most fixes are small once you know which browser is missing the feature.

• closedby attribute is new: Chrome 134, Edge 134, Firefox 137, and Safari 18.2 added the attribute. Older browsers fall back to listening for the cancel event and calling close() from a backdrop click handler.
• Internet Explorer and Opera Mini never supported it: IE 5.5 to 11 and every Opera Mini version render <dialog> as a block element with no modality, no ::backdrop, and no top-layer behaviour. Use dialog-polyfill or stop targeting these browsers.
• Animating display needs allow-discrete: Chrome 116, Firefox 129, and Safari 17.4 added transition-behavior: allow-discrete, which is required to animate the display property when opening or closing a dialog. Older browsers snap the dialog in and out.
• ::backdrop animation lagged in Firefox: Firefox painted the ::backdrop immediately for several releases before honouring opacity transitions. Firefox 110 and later runs the backdrop transition correctly.
• iOS Safari leaks scroll on the body: iOS Safari 15.4 to 16.3 let touch scroll events pass through a modal dialog so the body scrolled behind the backdrop. Safari 16.4 fixed it; older iOS still needs body { overflow: hidden } on open.
• Initial focus lands on the dialog: When no element inside the dialog has autofocus, Chrome and Firefox park focus on the dialog itself. Add autofocus to the primary action so screen readers announce the right control.
• open attribute is not interchangeable with show(): Setting the open attribute by hand shows a non-modal dialog without firing the cancel event and without putting the dialog in the top layer. Always call show() or showModal() instead.
• tabindex on the dialog is non-conforming: WHATWG forbids tabindex on <dialog> because the focus ring is managed automatically. Browsers ignore the attribute, and screen readers may announce a wrong tabbable target.

In my experience, the loudest dialog bug on real-device runs is iOS Safari 15.4 letting the page scroll behind a showModal() modal on iPhone, because the backdrop fires touchmove through to body. The fix is to call event.preventDefault() on the dialog's touchmove listener until you can drop iOS 16.3 and earlier.

How do you open and close an HTML dialog?

You open and close an HTML dialog by calling its showModal(), show(), or close() methods from JavaScript, or by submitting a form with method="dialog". The steps below open a modal, capture a return value, and close it on confirm.

• Mark up the dialog: Add a <dialog id="confirm-delete"> block with a heading, body copy, and a <form method="dialog"> containing a Cancel and a Delete button.
• Open the dialog modally: Call dialog.showModal() from a click handler on the trigger button. The browser places the dialog in the top layer, paints a ::backdrop, and makes the rest of the page inert.
• Wire up the close path: Set a value on each form button (<button value="cancel">, <button value="delete">) so submitting the form closes the dialog and writes the value to dialog.returnValue.
• Read the return value: Listen for the close event on the dialog and branch on dialog.returnValue. Trigger the destructive action only when the value is "delete".
• Handle Escape with cancel: Modal dialogs fire a cancel event when the user presses Escape. Call event.preventDefault() inside the listener if you need to keep the dialog open until validation passes.
• Confirm support before opening: Wrap the call site with if (typeof dialog.showModal === "function") so older browsers fall back to a polyfill or to a window.confirm prompt instead of throwing.

Paste this snippet into the DevTools console of any modern browser to mount a confirm dialog and read the return value.

// Mounts a confirm dialog, opens it modally, and logs the user's choice.
const dialog = document.createElement("dialog");
dialog.innerHTML = `
  <p>Delete this item permanently?</p>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="delete">Delete</button>
  </form>
`;
document.body.appendChild(dialog);

dialog.addEventListener("close", () => {
  console.log("returnValue:", dialog.returnValue);
});

if (typeof dialog.showModal === "function") {
  dialog.showModal();
} else {
  console.log("HTML <dialog> showModal() is not supported in this browser.");
}

Citations

All HTML dialog version numbers and platform notes in this guide come from these primary sources:

• WHATWG HTML Living Standard - the dialog element: html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
• MDN Web Docs - <dialog> element: developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog
• MDN Web Docs - HTMLDialogElement: developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement
• MDN Web Docs - HTMLDialogElement.showModal(): developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal
• MDN Web Docs - HTMLDialogElement.close(): developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/close
• MDN Web Docs - ::backdrop pseudo-element: developer.mozilla.org/en-US/docs/Web/CSS/::backdrop
• WebKit blog - New WebKit Features in Safari 15.4: webkit.org/blog/12445/new-webkit-features-in-safari-15-4
• Mozilla Firefox 98 release notes: mozilla.org/en-US/firefox/98.0/releasenotes
• web.dev - Dialog: web.dev/learn/html/dialog
• W3C WAI WCAG 2.1 - H102 Modal dialogs: w3.org/WAI/WCAG21/Techniques/html/H102
• WHATWG HTML - Popover attribute: html.spec.whatwg.org/multipage/popover.html
• Wikipedia - Dialog box: en.wikipedia.org/wiki/Dialog_box