Non-modal dialogs using popover commands Non-modal dialogs can be declaratively opened, closed, and toggled using the Popover API HTML attributes popovertarget and popovertargetaction , which can be defined on
The Popover API also provides properties that can be used to get and set the state in JavaScript. Closing dialogs It is important to provide a closing mechanism for every
Result Open the dialog by pressing the "Open dialog" button. You can close the dialog by selecting the "Close" button or pressing the Esc key. Popover API HTML attributes This example demonstrates how you can open and close a non-modal dialog using the popover popovertarget , and popovertargetaction HTML attributes of the Popover API The
Result Open the dialog by pressing the "Open dialog" button. You can close the dialog by selecting the "Close" button or pressing the Esc key. You can also close it by selecting outside the dialog, as it is non-modal. Using the dialog open attribute This example demonstrates how you can set the boolean open attribute on a
// "Show the dialog" button opens the dialog modally showButton.addEventListener("click", () => { dialog.showModal(); });
// "Close" button closes the dialog closeButton.addEventListener("click", () => { dialog.close(); }); Result When the modal dialog is displayed, it appears above any other dialogs that might be present. Everything outside the modal dialog is inert and interactions outside the dialog are blocked. Notice that when the dialog is open, with the exception of the dialog itself, interaction with the document is not possible; the "Show the dialog" button is mostly obfuscated by the almost opaque backdrop of the dialog and is inert. Handling the return value from the dialog This example demonstrates the returnValue of the
// "Show the dialog" button opens the
// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event. favDialog.addEventListener("close", (e) => { outputBox.value = favDialog.returnValue === "default" ? "No return value." : `ReturnValue: ${favDialog.returnValue}.`; // Have to check for "default" rather than empty string });
// Prevent the "confirm" button from the default behavior of submitting the form, and close the dialog with the `close()` method, which triggers the "close" event. confirmBtn.addEventListener("click", (event) => { event.preventDefault(); // We don't want to submit this fake form favDialog.close(selectEl.value); // Have to send the select box value here. }); Result Closing a dialog with a required form input When a form inside a dialog has a required input, the user agent will only let you close the dialog once you provide a value for the required input. To close such dialog, either use the formnovalidate attribute on the close button or call the close() method on the dialog object when the close button is clicked. html
jsCloseBtn.addEventListener("click", (e) => { e.preventDefault(); dialog.close(); }); Result From the output, we see it is impossible to close the dialog using the Normal close button. But the dialog can be closed if we bypass the form validation using the formnovalidate attribute on the Cancel button. Programmatically, dialog.close() will also close such dialog. Comparison of different closedby behaviors This example demonstrates the difference in behavior between different values of the closedby attribute. HTML We provide three
closeBtns.forEach((btn) => { btn.addEventListener("click", () => { btn.parentElement.close(); }); }); Result The rendered result is as follows: Try clicking each button to open a dialog. The first one can only be closed by clicking its "Close" button. The second one can also be closed via a device-specific user action such as pressing the Esc key. The third one has full "light-dismiss" behavior , so it can also be closed by clicking or tapping outside the dialog. Animating dialogs
CSS In the CSS, we include a @starting-style block that defines the transition starting styles for the opacity and transform properties, transition end styles on the dialog:open state, and default styles on the default dialog state to transition back to once the
/* Closed state of the dialog */ dialog { opacity: 0; transform: scaleY(0); transition: opacity 0.7s ease-out, transform 0.7s ease-out, overlay 0.7s ease-out allow-discrete, display 0.7s ease-out allow-discrete; /* Equivalent to transition: all 0.7s allow-discrete; */
/* Before open state */ /* Needs to be after the previous dialog:open rule to take effect, as the specificity is the same */ @starting-style { dialog:open { opacity: 0; transform: scaleY(0);
/* Transition the :backdrop when the dialog modal is promoted to the top layer */ dialog::backdrop { background-color: transparent; transition: display 0.7s allow-discrete, overlay 0.7s allow-discrete, background-color 0.7s; /* Equivalent to transition: all 0.7s allow-discrete; */
/* This starting-style rule cannot be nested inside the above selector because the nesting selector cannot represent pseudo-elements. */
@starting-style { dialog:open::backdrop { background-color: transparent; Note: In browsers that don't support the :open pseudo-class, you can use the attribute selector dialog[open] to style the
closeBtn.addEventListener("click", () => { dialogElem.close(); }); Result The code renders as follows: Technical summary Content categories Flow content sectioning root Permitted content Flow content Tag omission None, both the starting and ending tag are mandatory. Permitted parents Any element that accepts flow content Implicit ARIA role dialog Permitted ARIA roles alertdialog DOM interface HTMLDialogElement Specifications Specification HTML # the-dialog-element Browser compatibility See also HTMLDialogElement interface close event of the HTMLDialogElement interface cancel event of the HTMLDialogElement interface open property of the HTMLDialogElement interface inert global attribute for HTML elements ::backdrop CSS pseudo-element Web forms in the Learn area Help improve MDN Learn how to contribute This page was last modified on Feb 19, 2026 by MDN contributors View this page on GitHub Report a problem with this content