Web Component with progressive enhancements for the HTML <dialog> element
npm install @webfactoryde/dialog-utils
The <dialog-utils> Web Component is meant to be a lightweight wrapper and progressive enhancement for <dialog> elements that are used as modal dialogs.
The enhancements are:
autoopen: The Web Component supports opening a dialog immediately if anautoopenattribute is present on<dialog-utils>.commandforandcommand: The Web Component polyfills the Invoker Commands API to enable future-friendly, declarative linkup of buttons to show and close the dialog even in browsers that don't support the API yet. You can opt out of this if you prefer to write your own JavaScript logic to handle this functionality.closedby="any": The Web Component polyfills the declarative attribute for light dismissal of the dialog by a click outside of it.- Playing media: If the dialog contains an iframe, the Web Component will ensure that any media stops playing when the dialog is closed.
- Focus behaviour: You should use the declarative
autofocusattribute to indicate whether the dialog itself or a specific interactive child element should receive focus when the dialog is shown. If this is not an option, the Web Component accepts aautofocus-targetattribute with a valid DOM selector string as its value. The WC will then try to set theautofocusattribute on the first element that matches the selector. - Page scroll: If the dialog is opened as a modal, scrolling is disabled on the
<body>and re-enabled onclose. - The Web Component emits a custom
openevent when the dialog is opened.
- The JS file "dialog-utils.js" must be loaded. Depending on browser support requirements, transpilation for older browsers is recommended.
- Wrap your
<dialog>with<dialog-utils>. - Add a trigger and close
<button>with your desired markup (e.g. nested icon, attributes, translated text, etc.). The buttons need to be made identifiable withcommandforandcommandas per the specification, if you want to benefit from the ease-of-use polyfills. The Web Component leaves positioning and aesthetics of the buttons to the outside context.
<button commandfor="my-dialog" command="show-modal">Open my dialog</button>
<dialog-utils>
<dialog id="my-dialog>
<button commandfor="my-dialog" command="close">Close</button>
<h1>My modal</h1>
<p>Some content</p>
</dialog>
</dialog-utils>
The component emits a open event on the <dialog> element that includes information about whether the dialog is displayed as a modal via (bool) event.detail.isModal.
Caveat: This requires support for the toggle event which is Baseline 2023 but with a known regression for dialog in Safari 18 (fixed in Safari 26).
The component is exported to allow subclassing and extending its methods.
import {DialogUtils} from '@webfactoryde/dialog-utils';
class MyCustomDialogUtils extends DialogUtils {
onOpen(event) {
// call the parent method
super.onOpen?.(event);
// do your custom thing
}
}
customElements.define('my-custom-dialog-utils', MyCustomDialogUtils);