Introduction

Micromodal.js is a lightweight, configurable and a11y-enabled modal library written in pure JavaScript

It enables you to create WAI-ARIA guidelines compliant modal dialogs, with confidence and with minimal configuration. At just 1.9kb minified and gzipped, its a tiny library for big change.

Demo Modal

Following are some of the interactions handled by the library:-

Closing modal on overlay click

Closing modal on esc button press

button press Toggling aria-hidden attribute on modal

attribute on modal Trapping tab focus within the modal

Maintaining focus position before and after toggling modal

Focusing on the first focusable element within the modal

Installation

Micromodal is available on npm and can be installed from the command line via npm or yarn

npm install micromodal --save // via npm yarn add micromodal --save // via yarn

You can also download or link to the latest compiled version using the CDN.

https://unpkg.com/micromodal/dist/micromodal.min.js

Usage

Designed to be easy to use, it does most of the heavy lifting behind the scenes and exposes a simple api to interact with the dom.

Typically modals have an overlay which cover the rest of the content. To achieve this, it is normal to put the modal code just before the closing body tag, so that the modal overlay is relative to the body and covers the whole screen.

1. Add the modal markup

The following html structure is expected for the modal to work. It can of course be extended to suit your needs. As an example of the customization, see the source code of the demo modal here.

<!-- [1] --> <div id="modal-1" aria-hidden="true"> <!-- [2] --> <div tabindex="-1" data-micromodal-close> <!-- [3] --> <div role="dialog" aria-modal="true" aria-labelledby="modal-1-title" > <header> <h2 id="modal-1-title"> Modal Title </h2> <!-- [4] --> <button aria-label="Close modal" data-micromodal-close></button> </header> <div id="modal-1-content"> Modal Content </div> </div> </div> </div>

This is the outermost container of the modal. It's job is to toggle the display of the modal. It is important that every modal have a unique id . By default the aria-hidden will be true . Micromodal takes care of toggling the value when required.

. By default the will be . Micromodal takes care of toggling the value when required. This is the div which acts as the overlay for the modal. Notice the data-micromodal-close on it. This is a special attribute which indicates that the element that it is on should trigger the close of the modal on click. If we remove that attribute, clicking on the overlay will not close the modal anymore.

which acts as the overlay for the modal. Notice the on it. This is a special attribute which indicates that the element that it is on should trigger the close of the modal on click. If we remove that attribute, clicking on the overlay will not close the modal anymore. The role="dialog" attribute is used to inform assistive technologies that content within is separate from the rest of the page. Additionally, the aria-labelledby="modal-1-title" attribute points to the id of the modal title. This is to help identify the purpose of the modal.

attribute is used to inform assistive technologies that content within is separate from the rest of the page. Additionally, the attribute points to the of the modal title. This is to help identify the purpose of the modal. Ensuring that all buttons have a aria-label attribute which defines the action of the button. Notice the data-micromodal-close attribute is used on the button since we want to close the modal on press.

2. Add micromodal.js

If you included the compiled file from the CDN into your project, you will have access to a MicroModal global variable, which you can use to instantiate the module.

In cases with a modular workflow, you can directly import the module into your project.

import MicroModal from 'micromodal'; // es6 module var MicroModal = require('micromodal'); // commonjs module

3. Use with data attributes

Set data-micromodal-trigger="modal-1" on an element, like a button or link, on whose click you want to show the modal. The value of the attribute, in this case modal-1 should correspond to the id of the modal you want to toggle.

Then instantiate the MicroModal module, so that it takes care of all the bindings for you.

MicroModal.init();

Example:-

3.1. Custom data attributes

You can also specify custom attributes to open and close modals. Set data-custom-open="modal-1" to any element on the page and pass it in init method as parameter of openTrigger .

The working and usage is same as data-micromodal-trigger , but with your own defined data attribute, in this case it's data-custom-open

Similarly, you can also define custom close attribute. Example:-

<button data-custom-close="modal-1">close</button>

4. Use with javascript

You can also trigger and close modals programmatically using the show and close methods on the MicroModal object. Example:-

MicroModal.show('modal-id'); // [1] MicroModal.close('modal-id'); // [2]

The string passed to the show method must correspond to the id of the modal to be open. You can also pass in a config object in the show method and it will apply only to this modal.

method must correspond to the of the modal to be open. You can also pass in a config object in the method and it will apply only to this modal. The string passed to the close method must correspond to the id of the modal to be closed

Configuration

The init and show methods accept an optional configuration object. This allows you to set custom callbacks and control behaviour of the modal. Example:-

MicroModal.init({ onShow: modal => console.info(`${modal.id} is shown`), // [1] onClose: modal => console.info(`${modal.id} is hidden`), // [2] openTrigger: 'data-custom-open', // [3] closeTrigger: 'data-custom-close', // [4] openClass: 'is-open', // [5] disableScroll: true, // [6] disableFocus: false, // [7] awaitOpenAnimation: false, // [8] awaitCloseAnimation: false, // [9] debugMode: true // [10] });

onShow function This is fired when the modal is opening. The function receives the modal object as the first parameter and the trigger element as second parameter

onClose function This is fired when the modal is closing. The function receives the modal object as the first parameter and the trigger element as second parameter

openTrigger string Custom data attribute to open modal. Default is data-micromodal-trigger

closeTrigger string Custom data attribute to close modal. Default is data-micromodal-close

openClass string Custom class to be applied when modal is open. Default class is is-open

disableScroll boolean This disables scrolling on the page while the modal is open. The default value is false

disableFocus boolean Disable auto focus on first focusable element. Default is false

awaitOpenAnimation boolean Set this to true if using css animations to open the modal. This allows it to wait for the animation to finish before focusing on an element inside the modal. Default is false

awaitCloseAnimation boolean Set this to true if using css animations to hide the modal. This allows it to wait for the animation to finish before removing it from the DOM. Default is false

debugMode boolean This option suppresses the console warnings if passed as true . The default value is false

Styling

Micromodal does not make any stylistic choices about your modal and hence comes with no styling at all. It does not even toggle the visibility of the modal. You are free to style the modal in anyway you wish.

At the very least, we recommend the following bit of css to toggle the modal.

.modal { display: none; } .modal.is-open { display: block; }

In case you do want some default styles to get started quickly, you can refer to the styles and the corresponding markup of the demo modal here:-

Demo markup and styles.