Dialog
Dialog provides a bare bones baseline for building accessible modals or modal like UI elements such as fullscreen menus.
Features
- 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.
Install
$ npm install @rynpsc/dialog
Usage
The dialog constructor takes two parameters:
-
id- The ID of the element used as the dialog -
options- Configuration Object (see options)
HTML
<body>
<header></header>
<main></main>
<footer></footer>
<div class="dialog" id="my-dialog">
<!-- Dialog content -->
</div>
</body>JavaScript
import { dialog } from '@rynpsc/dialog';
const dialog = dialog('my-dialog', options);
if (dialog) {
dialog.create();
}CSS
.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'
}
API
dialog(id: string, options: Object)
Creates a dialog instance.
.open(element: HTMLElement | undefined | null = undefined, scroll: boolean = true)
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(element: HTMLElement | undefined | null = undefined, scroll: boolean = true)
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(force: boolean)
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()
Create the dialog after destroying it.
dialog.create();.destroy()
Destroy the dialog.
dialog.destroy();.on(string, function)
Subscribe to an event.
dialog.on(event);.off(string, function)
Unsubscribe to an event.
dialog.off(event);.isOpen
Returns a boolean indicating if the dialog is currently open.
dialog.isOpen;.initiated
Returns a boolean indicating if the dialog has been initiated.
dialog.isOpen;.id
The ID that was passed into the constructor.
dialog.id.element
The HTMLElement matching the ID passed into the constructor.
dialog.elementinstances
Returns an object of all the dialog instances.
import { instances } from '@rynpsc/dialog';
console.table(instances);getInstanceById(string)
Gets a dialog instance with the given id.
import { getInstanceById } from '@rynpsc/dialog';
const instance = getInstanceById('dialog');
if (instance) {
instance.open();
}Data Attribute API
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.
.mount()
Get and add event listeners to elements with data attributes.
domapi.mount();.unmount()
Remove event listeners from elements.
domapi.unmount();.openers
Get elements that will trigger open.
domapi.openers;.closers
Get elements that will trigger close.
domapi.closers;Events
Events are handled via the CustomEvent API.
open
Emitted when the dialog opens.
dialog.on('open', handler);This event can be cancelled, see Cancelling events.
close
Emitted when the dialog closes.
dialog.on('close', handler);This event can be cancelled, see Cancelling events.
create
dialog.on('create', handler);Emitted after the dialog is created.
destroy
dialog.on('destroy', handler);Emitted after the dialog is destroyed.
Cancelling events
The open and close events can be canceled by calling event.preventDefault in the event handler.
dialog.on('close', function(event) {
event.preventDefault();
});Browser Support
Requires the following API's:
- Array.from
- Array.prototype.filter
- Array.prototype.some
- CustomEvent
- DOMTokenList.contains
- Element.classList
- Element.matches
- Element.querySelectorAll
- HTMLElement.dataset
License
MIT