- Notifications
You must be signed in to change notification settings - Fork0
webfactory/dialog-utils
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Web Component with progressive enhancements for the HTML <dialog> element
npm install @webfactoryde/dialog-utilsThe<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 theInvoker 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 thedeclarative 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 thespecification, 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> <dialogmy-dialog" command="close">Close</button> <h1>My modal</h1> <p>Some content</p> </dialog></dialog-utils>The component emits aopen 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 thetoggle event which isBaseline 2023 but with aknown 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);About
Web Component with progressive enhancements for the HTML <dialog> element
Topics
Resources
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Releases
Packages0
Uh oh!
There was an error while loading.Please reload this page.