@webfactoryde/dialog-utils

v0.2.0

Published

a month ago

Web Component with progressive enhancements for the HTML <dialog> element

0High
0Medium
0Low

<dialog-utils>

Web Component with progressive enhancements for the HTML <dialog> element

Installation

npm install @webfactoryde/dialog-utils

Usage

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 an autoopen attribute is present on <dialog-utils>.
commandfor and command: 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 autofocus attribute 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 a autofocus-target attribute with a valid DOM selector string as its value. The WC will then try to set the autofocus attribute 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 on close.
The Web Component emits a custom open event when the dialog is opened.

Steps to implement:

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 with commandfor and command as 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.

Basic example

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

Events

`open`

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

Extending the component

The component is exported to allow subclassing and extending its methods.

Example

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);

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme