Skip to content

Dialog API ​

js
const dialog = document.querySelector('awc-dialog');

Properties ​

open ​

Whether the dialog is open. Setting it, or adding or removing the open attribute, shows or hides the dialog as show and hide do, so <awc-dialog open> opens modally, unlike a native <dialog open>. A removed dialog keeps open, and opens again when it's added back.

js
dialog.open;
// => false
dialog.open = true;

hideOnOutsideClick ​

Whether a press outside the dialog, released outside it, asks it to close. Defaults to true.

js
dialog.hideOnOutsideClick = false;

Methods ​

show ​

Shows the dialog. Emits awc-dialog:shown, but not the cancelable awc-dialog:show.

js
dialog.show();

hide ​

Hides the dialog, and any dialog nested in it first. Emits awc-dialog:hidden, but not the cancelable awc-dialog:hide.

js
await dialog.hide();

requestShow ​

Shows the dialog as if the user asked to. Emits a cancelable awc-dialog:show, and does nothing if it is prevented.

js
dialog.requestShow();

requestHide ​

Hides the dialog as if the user asked to. Emits a cancelable awc-dialog:hide, and does nothing if it is prevented.

js
await dialog.requestHide();

hideWithoutEmitting ​

Hides the dialog, and any dialog nested in it, without emitting any awc-dialog events. Like hide, it removes open.

js
dialog.hideWithoutEmitting();

Events ​

Events work as they do on native elements. A user action, or a requestShow or requestHide call, first emits a cancelable show or hide; calling preventDefault() on it stops the dialog from opening or closing. show(), hide() and changing open act directly, like a native <dialog>'s close(), and emit no show or hide. shown and hidden fire after every open and close, whatever caused it. Connecting, moving and removing the element emit nothing.

Like the other events, show and hide bubble. A listener on an element that contains other dialogs receives their show and hide too, so check event.target before preventing one.

NameBubblesCancelableDescription
awc-dialog:showtruetrueFires before the dialog opens for requestShow.
awc-dialog:showntruefalseFires after the dialog has opened.
awc-dialog:hidetruetrueFires before the dialog closes for a user action or requestHide: a close button, Escape, or an outside click.
awc-dialog:hiddentruefalseFires after the dialog has closed, including when a <form method="dialog"> closes it.

TIP

Browsers let a page keep a dialog open only on the first Escape after the user interacts with it. If the user presses Escape again, the dialog closes without an awc-dialog:hide, and only awc-dialog:hidden fires.

Released under the MIT License.