Dialog

Modal content container

Demo

API

Tag

Name Type Content
m-dialog Custom Element Any content. The first element with autofocus, if any, will receive focus when the Dialog is opened.

Attributes

Name Value Description
open Boolean attribute Will open the Dialog when added or close when removed. It is the same as calling showModal() and close(). If you want the dialog displayed "modelessly", you have to call the show method.

Events

Name Detail Description
close None Fired after the Dialog was closed. Note that the Dialog and its content are preserved in the DOM, so forms, for example, will retain their values. Your app should reset the form if that's what your use case requires.

Beware of infinite loops when implementing a done/close/cancel button. Only call close() on the Dialog if the event is not this event, e.g. if (e.type !== 'close') { myDialog.close() }.

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

What about <dialog>?

This element attempts to match the HTMLDialogElement interface as close as possible, so when browser support for <dialog> is sufficient it will be removed from M- in favor of the native element. Breaking changes should be limited to just the "m-" prefix.

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".