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

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]
  disableScroll: true // [4]
});
        
  • 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.
  • disableScroll (boolean) This option will disbable scrolling on the page while the modal is open. The default value is false.

4. Use with javascript

You can also triggera 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

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.