Will open the Dialog when added or close when removed. If you want the dialog displayed "modelessly", you have to call the show method.
Events
Name
Detail
Description
close
None
MDN says: "Fired when the dialog is closed, whether with the escape key, the HTMLDialogElement.close() method, or via submitting a form within the dialog with
method="dialog"."
cancel
None
MDN says: "Fired when the user dismisses the current open dialog with the escape key."
Methods
Signature
Description
close([returnValue])
MDN says: "Closes the dialog. An optional DOMString may be passed as an argument, updating the returnValue of the the dialog." Also note that the Dialog and its contents are still present in the DOM (e.g. forms still have user-entered values, so reset it if that's what your use case requires).
show()
MDN says: "Displays the dialog modelessly, i.e. still allowing interaction with content outside of the dialog."
showModal()
MDN says: "Displays the dialog as a modal, over the top of any other dialogs that might be present. Interaction outside the dialog is blocked."
Guidelines
Close button
Dialog elements do not come with a button to close themselves, so Mdash includes style-only support for one. Add <button slot="close" type="remove"> and Mdash will style it for you, but your application must implement the click handler (e.g. calling the dialog's close method or removing its open attribute). Note that this is required only if a dialog doesn't implement any other buttons for closing. Here's a basic example:
Forms and DOM state
The state of the content is controlled by your application. Dialog does not change the state of its children other than moving them into a containing div on init. Forms and all other elements will initialize the way they are provided by the application and will continue to remain untouched even when the Dialog is closed. For example, if a Dialog is used to present a login form the application should remove the Dialog completely or reset the form after successful authentication. If left alone the Dialog and the login form inside it will contain the user's credentials. It's your content; you have to manage it.
Accessibility
The necessary ARIA attributes are added automatically; however, if your Dialog "contains an alert message" you should set role="alertdialog".