This element includes theglobal attributes.

closedby

Specifies the types of user actions that can be used to close the<dialog> element. This attribute distinguishes three methods by which a dialog might be closed:

• Alight dismiss user action, in which the<dialog> is closed when the user clicks or taps outside it. This is equivalent to the"light dismiss" behavior of "auto" state popovers.
• Aplatform-specific user action, such as pressing theEsc key on desktop platforms, or a "back" or "dismiss" gesture on mobile platforms.
• A developer-specified mechanism such as a<button> with aclick handler that invokesHTMLDialogElement.close() or a<form> submission.

Possible values are:

any

The dialog can be dismissed using any of the three methods.

closerequest

The dialog can be dismissed with a platform-specific user action or a developer-specified mechanism.

none

The dialog can only be dismissed with a developer-specified mechanism.

If the<dialog> element does not have a validclosedby value specified, then

• if it was opened usingshowModal(), it behaves as if the value was"closerequest"
• otherwise, it behaves as if the value was"none".

open

Indicates that the dialog box is active and is available for interaction. If theopen attribute is not set, the dialog box will not be visible to the user.It is recommended to use the.show() or.showModal() method to render dialogs, rather than theopen attribute. If a<dialog> is opened using theopen attribute, it is non-modal.

Note:While you can toggle between the open and closed states of non-modal dialog boxes by toggling the presence of theopen attribute, this approach is not recommended. Seeopen for more information.

• HTML<form> elements can be used to close a dialog box if they have the attributemethod="dialog" or if the button used to submit the form hasformmethod="dialog" set. When a<form> within a<dialog> is submitted via thedialog method, the dialog box closes, the states of the form controls are saved but not submitted, and thereturnValue property gets set to the value of the button that was activated.
• The CSS::backdrop pseudo-element can be used to style the backdrop of a modal dialog, which is displayed behind the<dialog> element when the dialog is displayed using theHTMLDialogElement.showModal() method. For example, this pseudo-element could be used to blur, darken, or otherwise obfuscate the inert content behind the modal dialog.
• Theautofocus attribute should be added to the element the user is expected to interact with immediately upon opening a modal dialog. If no other element involves more immediate interaction, it is recommended to addautofocus to the close button inside the dialog, or the dialog itself if the user is expected to click/activate it to dismiss.
• Do not add thetabindex property to the<dialog> element as it is not interactive and does not receive focus. The dialog's contents, including the close button contained in the dialog, can receive focus and be interactive.

When implementing a dialog, it is important to consider the most appropriate place to set user focus. When usingHTMLDialogElement.showModal() to open a<dialog>, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using theautofocus attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the<dialog> element itself may provide the best initial focus placement.

Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button.

By default, a dialog invoked by theshowModal() method can be dismissed by pressing theEsc key. A non-modal dialog does not dismiss via theEsc key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect theEsc key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing theEsc key should close only the last shown dialog. When using<dialog>, this behavior is provided by the browser.

While dialogs can be created using other elements, the native<dialog> element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed.

The<dialog> element is exposed by browsers in a manner similar to custom dialogs that use the ARIArole="dialog" attribute.<dialog> elements invoked by theshowModal() method implicitly havearia-modal="true", whereas<dialog> elements invoked by theshow() method or displayed using theopen attribute or by changing the defaultdisplay of a<dialog> are exposed as[aria-modal="false"]. When implementing modal dialogs, everything other than the<dialog> and its contents should be rendered inert using theinert attribute. When using<dialog> along with theHTMLDialogElement.showModal() method, this behavior is provided by the browser.

This example demonstrates the creation of a non-modal dialog by using only HTML. Because of the booleanopen attribute in the<dialog> element, the dialog appears open when the page loads. The dialog can be closed by clicking the "OK" button because themethod attribute in the<form> element is set to"dialog". In this case, no JavaScript is needed to close the form.

<dialog open>  <p>Greetings, one and all!</p>  <form method="dialog">    <button>OK</button>  </form></dialog>

Result

This dialog is initially open because of the presence of theopen attribute. Dialogs that are displayed using theopen attribute are non-modal. After clicking "OK", the dialog gets dismissed, leaving the Result frame empty. When the dialog is dismissed, there is no method provided to reopen it. For this reason, the preferred method to display non-modal dialogs is by using theHTMLDialogElement.show() method. It is possible to toggle the display of the dialog by adding or removing the booleanopen attribute, but it is not the recommended practice.

This example demonstrates a modal dialog with agradient backdrop. The.showModal() method opens the modal dialog when the "Show the dialog" button is activated. The dialog can be closed by pressing theEsc key or via theclose() method when the "Close" button within the dialog is activated.

When a dialog opens, the browser, by default, gives focus to the first element that can be focused within the dialog. In this example, theautofocus attribute is applied to the "Close" button, giving it focus when the dialog opens, as this is the element we expect the user will interact with immediately after the dialog opens.

HTML

<dialog>  <button autofocus>Close</button>  <p>This modal dialog has a groovy backdrop!</p></dialog><button>Show the dialog</button>

CSS

We can style the backdrop of the dialog by using the::backdrop pseudo-element.

::backdrop {  background-image: linear-gradient(    45deg,    magenta,    rebeccapurple,    dodgerblue,    green  );  opacity: 0.75;}

JavaScript

The dialog is opened modally using the.showModal() method and closed using the.close() or.requestClose() methods.

const dialog = document.querySelector("dialog");const showButton = document.querySelector("dialog + button");const closeButton = document.querySelector("dialog button");// "Show the dialog" button opens the dialog modallyshowButton.addEventListener("click", () => {  dialog.showModal();});// "Close" button closes the dialogcloseButton.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.

This example demonstrates thereturnValue of the<dialog> element and how to close a modal dialog by using a form. By default, thereturnValue is the empty string or the value of the button that submits the form within the<dialog> element, if there is one.

This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a<select> and two<button> elements, which default totype="submit". An event listener updates the value of the "Confirm" button when the select option changes. If the "Confirm" button is activated to close the dialog, the current value of the button is the return value. If the dialog is closed by pressing the "Cancel" button, thereturnValue iscancel.

When the dialog is closed, the return value is displayed under the "Show the dialog" button. If the dialog is closed by pressing theEsc key, thereturnValue is not updated, and theclose event doesn't occur, so the text in the<output> is not updated.

HTML

<!-- A modal dialog containing a form --><dialog>  <form>    <p>      <label>        Favorite animal:        <select>          <option value="default">Choose…</option>          <option>Brine shrimp</option>          <option>Red panda</option>          <option>Spider monkey</option>        </select>      </label>    </p>    <div>      <button value="cancel" formmethod="dialog">Cancel</button>      <button value="default">Confirm</button>    </div>  </form></dialog><p>  <button>Show the dialog</button></p><output></output>

JavaScript

const showButton = document.getElementById("showDialog");const favDialog = document.getElementById("favDialog");const outputBox = document.querySelector("output");const selectEl = favDialog.querySelector("select");const confirmBtn = favDialog.querySelector("#confirmBtn");// "Show the dialog" button opens the <dialog> modallyshowButton.addEventListener("click", () => {  favDialog.showModal();});// "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

The above examples demonstrate the following three methods of closing modal dialogs:

• By submitting the form within the dialog form using thedialog method (as seen in theHTML-only example).
• By pressing theEsc key.
• By calling theHTMLDialogElement.close() method (as seen in themodal example).In this example, the "Cancel" button closes the dialog via thedialog form method and the "Confirm" button closes the dialog via theHTMLDialogElement.close() method.

The "Cancel" button includes theformmethod="dialog" attribute, which overrides the<form>'s defaultGET method. When a form's method isdialog, the state of the form is saved but not submitted, and the dialog gets closed.

Without anaction, submitting the form via the defaultGET method causes a page to reload. We use JavaScript to prevent the submission and close the dialog with theevent.preventDefault() andHTMLDialogElement.close() methods, respectively.

It is important to provide a closing mechanism within everydialog element. TheEsc key does not close non-modal dialogs by default, nor can one assume that a user will even have access to a physical keyboard (e.g., someone using a touch screen device without access to a keyboard).

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 theformnovalidate attribute on the close button or call theclose() method on the dialog object when the close button is clicked.

<dialog>  <form method="dialog">    <p>      <label>        Favorite animal:        <input type="text" required />      </label>    </p>    <div>      <input type="submit" value="Normal close" />      <input        type="submit"               value="Novalidate close"        formnovalidate />      <input type="submit" value="JS close" />    </div>  </form></dialog><p>  <button>Show the dialog</button></p><output></output>

[type="submit"] {  margin-right: 1rem;}

JavaScript

const showBtn = document.getElementById("show-dialog");const dialog = document.getElementById("dialog");const jsCloseBtn = dialog.querySelector("#js-close");showBtn.addEventListener("click", () => {  dialog.showModal();});jsCloseBtn.addEventListener("click", (e) => {  e.preventDefault();  dialog.close();});

Result

From the output, we see it is impossible to close the dialog using theNormal close button. But the dialog can be closed if we bypass the form validation using theformnovalidate attribute on theCancel button. Programmatically,dialog.close() will also close such dialog.

This example demonstrates the difference in behavior between different values of theclosedby attribute.

HTML

We provide three<button> elements and three<dialog> elements. Each button will be programmed to open a different dialog that demonstrates the behavior of one of the three values of theclosedby attribute —none,closerequest, andany. Note that each<dialog> element contains a<button> element that will be used to close it.

<p>Choose a <code>&lt;dialog&gt;</code> type to show:</p><div>  <button><code>closedby="none"</code></button>  <button>    <code>closedby="closerequest"</code>  </button>  <button><code>closedby="any"</code></button></div><dialog closedby="none">  <h2><code>closedby="none"</code></h2>  <p>    Only closable using a specific provided mechanism, which in this case is    pressing the "Close" button below.  </p>  <button>Close</button></dialog><dialog closedby="closerequest">  <h2><code>closedby="closerequest"</code></h2>  <p>Closable using the "Close" button or the Esc key.</p>  <button>Close</button></dialog><dialog closedby="any">  <h2><code>closedby="any"</code></h2>  <p>    Closable using the "Close" button, the Esc key, or by clicking outside the    dialog. "Light dismiss" behavior.  </p>  <button>Close</button></dialog>

body {  font-family: sans-serif;}#controls {  display: flex;  justify-content: space-around;}dialog {  width: 480px;  border-radius: 5px;  border-color: rgb(0 0 0 / 0.3);}dialog h2 {  margin: 0;}dialog p {  line-height: 1.4;}

JavaScript

Here we assign different variables to reference the main control<button> elements, the<dialog> elements, and the "Close"<button> elements inside the dialogs. First we assign aclick event listener to each control button usingaddEventListener, the event handler function of which opens the associated<dialog> element viashowModal(). We then loop through the "Close"<button> references, assigning each one aclick event handler function that closes its<dialog> element viaclose().

const noneBtn = document.getElementById("none-btn");const closerequestBtn = document.getElementById("closerequest-btn");const anyBtn = document.getElementById("any-btn");const noneDialog = document.querySelector("[closedby='none']");const closerequestDialog = document.querySelector("[closedby='closerequest']");const anyDialog = document.querySelector("[closedby='any']");const closeBtns = document.querySelectorAll(".close");noneBtn.addEventListener("click", () => {  noneDialog.showModal();});closerequestBtn.addEventListener("click", () => {  closerequestDialog.showModal();});anyBtn.addEventListener("click", () => {  anyDialog.showModal();});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 theEsc key. The third one has full"light-dismiss" behavior, so it can also be closed by clicking or tapping outside the dialog.

<dialog>s are set todisplay: none; when hidden anddisplay: block; when shown, as well as being removed from / added to thetop layer and theaccessibility tree. Therefore, for<dialog> elements to be animated thedisplay property needs to be animatable.Supporting browsers animatedisplay with a variation on thediscrete animation type. Specifically, the browser will flip betweennone and another value ofdisplay so that the animated content is shown for the entire animation duration.

So for example:

• When animatingdisplay fromnone toblock (or another visibledisplay value), the value will flip toblock at0% of the animation duration so it is visible throughout.
• When animatingdisplay fromblock (or another visibledisplay value) tonone, the value will flip tonone at100% of the animation duration so it is visible throughout.

Transitioning dialog elements

When animating<dialog>s with CSS transitions, the following features are required:

@starting-style at-rule

Provides a set of starting values for properties set on the<dialog> that you want to transition from every time it is opened. This is needed to avoid unexpected behavior. By default, CSS transitions only occur when a property changes from one value to another on a visible element; they are not triggered on elements' first style updates, or when thedisplay type changes fromnone to another type.

display property

Adddisplay to the transitions list so that the<dialog> will remain asdisplay: block (or another visibledisplay value set on the dialog's open state) for the duration of the transition, ensuring the other transitions are visible.

overlay property

Includeoverlay in the transitions list to ensure the removal of the<dialog> from the top layer is deferred until the transition completes, again ensuring the transition is visible.

transition-behavior property

Settransition-behavior: allow-discrete on thedisplay andoverlay transitions (or on thetransition shorthand) to enable discrete transitions on these two properties that are not by default animatable.

Here is a quick example to show what this might look like.

HTML

The HTML contains a<dialog> element, plus a button to show the dialog. Additionally, the<dialog> element contains another button to close itself.

<dialog>  Content here  <button>close</button></dialog><button>Show Modal</button>

CSS

In the CSS, we include a@starting-style block that defines the transition starting styles for theopacity andtransform properties, transition end styles on thedialog:open state, and default styles on the defaultdialog state to transition back to once the<dialog> has appeared. Note how the<dialog>'stransition list includes not only these properties, but also thedisplay andoverlay properties, each withallow-discrete set on them.

We also set a starting style value for thebackground-color property on the::backdrop that appears behind the<dialog> when it opens, to provide a nice darkening animation. Thedialog:open::backdrop selector selects only the backdrops of<dialog> elements when the dialog is open.

/* Open state of the dialog  */dialog:open {  opacity: 1;  transform: scaleY(1);}/* 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: rgb(0 0 0 / 0%);  transition:    display 0.7s allow-discrete,    overlay 0.7s allow-discrete,    background-color 0.7s;  /* Equivalent to  transition: all 0.7s allow-discrete; */}dialog:open::backdrop {  background-color: rgb(0 0 0 / 25%);}/* This starting-style rule cannot be nested inside the above selectorbecause the nesting selector cannot represent pseudo-elements. */@starting-style {  dialog:open::backdrop {    background-color: rgb(0 0 0 / 0%);  }}

JavaScript

The JavaScript adds event handlers to the show and close buttons causing them to show and close the<dialog> when they are clicked:

const dialogElem = document.getElementById("dialog");const showBtn = document.querySelector(".show");const closeBtn = document.querySelector(".close");showBtn.addEventListener("click", () => {  dialogElem.showModal();});closeBtn.addEventListener("click", () => {  dialogElem.close();});

Result

The code renders as follows:

dialog keyframe animations

When animating a<dialog> with CSS keyframe animations, there are some differences to note from transitions:

• You don't provide a@starting-style.
• You include thedisplay value in a keyframe; this will be thedisplay value for the entirety of the animation, or until another non-none display value is encountered.
• You don't need to explicitly enable discrete animations; there is no equivalent toallow-discrete inside keyframes.
• You don't need to setoverlay inside keyframes either; thedisplay animation handles the animation of the<dialog> from shown to hidden.

Let's have a look at an example so you can see what this looks like.

HTML

First, the HTML contains a<dialog> element, plus a button to show the dialog. Additionally, the<dialog> element contains another button to close itself.

<dialog>  Content here  <button>close</button></dialog><button>Show Modal</button>

CSS

The CSS defines keyframes to animate between the closed and shown states of the<dialog>, plus the fade-in animation for the<dialog>'s backdrop. The<dialog> animations include animatingdisplay to make sure the actual visible animation effects remain visible for the whole duration. Note that it wasn't possible to animate the backdrop fade out — the backdrop is immediately removed from the DOM when the<dialog> is closed, so there is nothing to animate.

dialog {  animation: fade-out 0.7s ease-out;}dialog:open {  animation: fade-in 0.7s ease-out;}dialog:open::backdrop {  animation: backdrop-fade-in 0.7s ease-out forwards;}/* Animation keyframes */@keyframes fade-in {  0% {    opacity: 0;    transform: scaleY(0);    display: none;  }  100% {    opacity: 1;    transform: scaleY(1);    display: block;  }}@keyframes fade-out {  0% {    opacity: 1;    transform: scaleY(1);    display: block;  }  100% {    opacity: 0;    transform: scaleY(0);    display: none;  }}@keyframes backdrop-fade-in {  0% {    background-color: rgb(0 0 0 / 0%);  }  100% {    background-color: rgb(0 0 0 / 25%);  }}body,button {  font-family: system-ui;}

JavaScript

Finally, the JavaScript adds event handlers to the buttons to enable showing and closing the<dialog>:

const dialogElem = document.getElementById("dialog");const showBtn = document.querySelector(".show");const closeBtn = document.querySelector(".close");showBtn.addEventListener("click", () => {  dialogElem.showModal();});closeBtn.addEventListener("click", () => {  dialogElem.close();});

Result

The code renders as follows:

• HTMLDialogElement interface
• close event of theHTMLDialogElement interface
• cancel event of theHTMLDialogElement interface
• open property of theHTMLDialogElement interface
• inert global attribute for HTML elements
• ::backdrop CSS pseudo-element
• Web forms in the Learn area