A11y Dialog Component

a11y-dialog-component is a fast, lightweight and flexible vanilla JavaScript library to create accessible modal, non-modal or tooltip dialogs.

These dialogs are fully accessible according to WAI-ARIA Authoring Practices 1.2.

Getting Started

Installing

A simple and fast way to get started is to include this script on your page. This will create the global variable Dialog

<script src="https://cdn.jsdelivr.net/npm/a11y-dialog-component@5.5.1/dist/a11y-dialog-component.min.js"></script>

If you prefer to install a11y-dialog-component locally in your project, you can either:

Install with NPM

npm install a11y-dialog-component

Install with Yarn

yarn add a11y-dialog-component

Basic Usage

Should you install a11y-dialog-component locally, you can import it as ES module like the following:

import Dialog from 'a11y-dialog-component';

It's also possible to use the require CommonJS syntax:

const Dialog = require('a11y-dialog-component').default;

Finally, let's create a basic dialog:

HTML

<!-- Opening trigger -->
<button type="button" class="js-dialog-open">Open dialog</button>

<!-- Dialog -->
<div class="c-dialog js-dialog">
  <h2 id="dialog-title">Hello! I'm an accessible dialog</h2>
  <button type="button" class="js-dialog-close">Cancel</button>
</div>

JavaScript

const dialog = new Dialog('.js-dialog', {
  openingSelector: '.js-dialog-open',
  closingSelector: '.js-dialog-close',
  labelledby: 'dialog-title',
});

CSS

.c-dialog[aria-hidden='true'] {
  display: none;
}

This previous code will generate an accessible dialog:

<!-- Opening trigger -->
<button type="button" class="js-dialog-open" aria-haspopup="dialog">Open dialog</button>

<!-- Dialog -->
<div
  class="c-dialog js-dialog"
  role="dialog"
  tabindex="-1"
  aria-hidden="true"
  aria-modal="true"
  aria-labelledby="dialog-title"
>
  <h2 id="dialog-title">Hello! I'm an accessible dialog</h2>
  <button type="button" class="js-dialog-close">Cancel</button>
</div>

Configuration

Global

Use the setDefaults() function to change the default configuration for dialogs. It will apply these settings to every future instance.

import Dialog, { setDefaults } from 'a11y-dialog-component';

setDefaults({
  documentSelector: '.js-page',
  delay: 400,
});

Below is a list of all possible options to change the default configuration.

Option	Default	Value	Description
documentSelector	`.js-document`	`String`	CSS selector used to target the main document.
documentDisabledClass	`is-disabled`	`String`	Add a class on the document (defined by `documentSelector`) while the dialog is open and if `disableScroll: true`.
openingTriggerActiveClass	`is-active`	`String`	Add a class on the opening trigger while the dialog is open.
delay	`200`	`Number`	Delay in ms once a trigger event is fired before the dialog autofocus. Usually matches with the CSS transition value to open or close this dialog.

Options

Below is a list of all possible options you can pass to a dialog.

Option	Default	Value	Description
onOpen	`noop`	`Function`	Lifecycle function invoked when the dialog is opening. The function receives the dialog object as the first parameter and the opening trigger as the second parameter.
onClose	`noop`	`Function`	Lifecycle function invoked when the dialog is closing. The function receives the dialog object as the first parameter and the closing trigger as the second parameter.
openingSelector	`""`	`String`	CSS selector used to open the dialog.
closingSelector	`""`	`String`	CSS selector used to close the dialog.
backdropSelector	`""`	`String`	CSS selector used to include a backdrop element which close the dialog on click.
helperSelector	`""`	`String`	CSS selector used to add active class name(*) while the dialog is open.
labelledby	`""`	`String`	ID selector to provide a dialog label (a11y compliant).
describedby	`""`	`String`	ID selector to provide a dialog description (a11y compliant).
isModal	`true`	`Boolean`	If `true`, tells assistive technologies that the windows underneath the current dialog are not available for interaction `aria-modal="true"`.
isTooltip	`false`	`Boolean`	If `true`, click outside the current dialog to close it.
isCreated	`true`	`Boolean`	If `true`, create the dialog when initialized. If disabled, then you need to create it manually by using `create()` method.
isOpen	`false`	`Boolean`	If `true`, open the dialog when initialized.
disableScroll	`true`	`Boolean`	If `true`, disable scrolling on the page while the dialog is open.
enableAutoFocus	`true`	`Boolean`	If `true`, focus moves to an element contained in the dialog when it opens.
openingTriggerActiveClass*	`is-active`	`String`	Add a class on the opening trigger and helper selectors while the dialog is open.
delay	`200`	`Number`	Delay in ms once a trigger event is fired before the dialog autofocus. Usually matches with the CSS transition value to open or close this dialog.

Methods

Dialog instances have 5 methods available which allow you to control the dialog without the use of UI events.

Open the dialog

dialog.open();

Close the dialog

dialog.close();

Toggle the dialog

dialog.toggle();

Destroy the dialog

dialog.destroy();

Create the dialog

The create() method is automatically called on instantiation so there is no need to call it again directly (unless you have destroyed the dialog previously).

dialog.create();

Demos

Didn't find the recipe that exactly matches your case? We have demos!

The demos folder contains 10 use cases of a11y-dialog-component. You might find there what you're looking for.

Deployment

On production use files only from dist/ folder, there will be the most stable versions.

a11y-dialog-component uses Rollup to build a development and production versions.

Install Rollup npm install --global rollup
Clone Github repo git clone https://github.com/jonathanlevaillant/a11y-dialog-component.git
Install all dependencies, in repo's root npm install

Development build

npm run dev

Development files (iife) will be available in demos/js/ folder.

Production build

npm run build

Production files (cjs, esm, iife) will be available in dist/ folder.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

Jonathan Levaillant - Initial work - jonathanlevaillant

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

jonathanlevaillant/a11y-dialog-component