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.
Following are some of the interactions handled by the library:-
- Closing modal on overlay click
- Closing modal on
esc
button press - Toggling
aria-hidden
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" aria-describedby="modal-1-content">
<!-- [4] -->
<div role="document">
<header>
<h3 id="modal-1-title">
Modal Title
</h3>
<!-- [5] -->
<button aria-label="Close modal" aria-controls="modal-1" data-micromodal-close></button>
</header>
<main id="modal-1-content">
Modal Content
</main>
</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 thearia-hidden
will betrue
. Micromodal takes care of toggling the value when required. -
This is the
div
which acts as the overlay for the modal. Notice thedata-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. -
The
role="dialog"
attribute is used to inform assistive technologies that content within is separate from the rest of the page. Additionally, thearia-labelledby="modal-1-title"
attribute points to theid
of the modal title. This is to help identify the purpose of the modal. Similarly, thearia-describedby
points to theid
of the modal content element. -
The wrapper with the
role="document
is not required to be present but is recommended. It helps inform screen-readers and other assistive technologies about a separate document context within the modal. -
Ensuring that all buttons have a
aria-label
attribute which defines the action of the button. Notice thedata-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:-
The init
method also accepts and optional configuration object. This can be used to pass hooks to be executed on the modal open and modal close events. Example:-
MicroModal.init({
onClose: modal => console.info(`${modal.id} is hidden`), // [1]
onShow: modal => console.info(`${modal.id} is shown`), // [2]
debugMode: true // [3]
});
-
onShow (function)
This is fired when the modal is opening. The function receives the modal object as the first parameter. -
onClose (function)
This is fired when the modal is closing. The function receives the modal object as the first parameter. -
debugMode (boolean)
This option will suppress console warnings if passed true. The default value is false.
4. Use with javascript
You can also trigger modals programmatically using the show
method on the MicroModal
object. Example:-
MicroModal.show('modal-id'); // [1]
-
The string passed to the
show
method must correspond to theid
of the modal to be toggled
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[aria-hidden='true'] {
display: none;
}
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.