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" >


      <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. Its 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.
  • 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.
  • 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.
  • 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:-

Trigger Modal

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.
  • 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.