Dialog provides a bare bones baseline for building accessible modals or modal like UI elements such as fullscreen menus.
- Takes care of adding the correct aria roles and attributes.
- Sends and traps focus within the dialog.
- Provides an event API via CustomEvents.
- Simple data attribute API for opening and closing.
$ npm install @rynpsc/dialog
The dialog constructor takes two parameters:
id- The ID of the element used as the dialogoptions- Configuration Object (see options)
<body>
<header></header>
<main></main>
<footer></footer>
<div class="dialog" id="my-dialog">
<!-- Dialog content -->
</div>
</body>import { dialog } from '@rynpsc/dialog';
const dialog = dialog('my-dialog', options);
if (dialog) {
dialog.create();
}.dialog {
visibility: hidden;
}
.dialog.is-open {
visibility: visible;
}For an example on how to animate the dialog see the CodePen demo.
## Options
```js
{
// ID of HTMLElement to use in aria-labelledby or a string to use as the aria-label.
label: 'Dialog',
// ID of HTMLElement to use in aria-describedby.
description: '',
// Set dialog role to alertdialog.
alert: false,
// Enable automatic focus management.
manageFocus: true,
// The class applied to elements.dialog when open.
openClass: 'is-open'
}
Creates a dialog instance.
Open the dialog.
The optional element argument can be used to control the element that gets focused on opening. If undefined (the default) the first focusalbe element will be focused or the first element with the data-dialog-autofocus attribute. If null is passed, focus will not be redirected.
dialog.open(element);Close the dialog.
The optional element argument can be used to control the element that gets focused on closing. If not set (undefined) the element that had focus before calling open will be focused. If null is passed, focus will not be redirected.
dialog.close();Toggle the dialog between opened and closed.
dialog.toggle();If the optional force parameter evaluates to true, open the dialog, if false, close the dialog.
Create the dialog after destroying it.
dialog.create();Destroy the dialog.
dialog.destroy();Subscribe to an event.
dialog.on(event);Unsubscribe to an event.
dialog.off(event);Returns a boolean indicating if the dialog is currently open.
dialog.isOpen;Returns a boolean indicating if the dialog has been initiated.
dialog.isOpen;The ID that was passed into the constructor.
dialog.idThe HTMLElement matching the ID passed into the constructor.
dialog.elementReturns an object of all the dialog instances.
import { instances } from '@rynpsc/dialog';
console.table(instances);Gets a dialog instance with the given id.
import { getInstanceById } from '@rynpsc/dialog';
const instance = getInstanceById('dialog');
if (instance) {
instance.open();
}This library contains an optional data attribute API that enables opening and closing a dialog instance.
import { domapi } from '@rynpsc/dialog';
domapi.mount()<div id="dialog">
<!-- Dialog content -->
</div>
<button data-dialog-open="dialog">Open Dialog</button>
<button data-dialog-close="dialog">Close Dialog</button>Where "dialog" is the ID of the dialog element.
Get and add event listeners to elements with data attributes.
domapi.mount();Remove event listeners from elements.
domapi.unmount();Get elements that will trigger open.
domapi.openers;Get elements that will trigger close.
domapi.closers;Events are handled via the CustomEvent API.
Emitted when the dialog opens.
dialog.on('open', handler);This event can be cancelled, see Cancelling events.
Emitted when the dialog closes.
dialog.on('close', handler);This event can be cancelled, see Cancelling events.
dialog.on('create', handler);Emitted after the dialog is created.
dialog.on('destroy', handler);Emitted after the dialog is destroyed.
The open and close events can be canceled by calling event.preventDefault in the event handler.
dialog.on('close', function(event) {
event.preventDefault();
});Requires the following API's:
- Array.from
- Array.prototype.filter
- Array.prototype.some
- CustomEvent
- DOMTokenList.contains
- Element.classList
- Element.matches
- Element.querySelectorAll
- HTMLElement.dataset
MIT