A <dialog> is hidden until it has the open attribute. There are two ways to show it:
show()opens it non-modally. The rest of the page stays interactive, and by default Escape doesn't close it.showModal()opens it modally. It goes into the top layer, above everyz-index, with a::backdropbehind it. The rest of the document becomes inert: no clicks, no focus. Escape closes it, and it matches:modal.
Both move focus into the dialog (its autofocus descendant, otherwise its first focusable element), and closing returns focus to whatever had it before.
Three ways to close it, all ending in the same steps:
close(value)closes immediately.requestClose(value)first fires a cancelablecancelevent, exactly as Escape does. Use it for your own close buttons so onecancelhandler covers every route.- A
<form method="dialog">inside it closes the dialog on submit instead of sending a request. The submit button'svaluebecomes the result. Validation still runs first.
The result is stored in returnValue, a string. It is updated only when a value is given, and it isn't reset when the dialog reopens, so reset it yourself before showModal(). After closing, a close event fires as a separate task; open is already false by then.
closedby chooses what the user can do: any (Escape or a click outside), closerequest (Escape only, the modal default) or none (the non-modal default). requestClose() ignores it. Chrome 134 and Firefox 141 support closedby; Safari doesn't yet. Buttons can also act without script: commandfor="id" with command="show-modal", "close" or "request-close" (Chrome 135, Firefox 144, Safari 26.2).
Don't remove the open attribute by hand: no close event fires, and a modal dialog leaves the page blocked.