Robust and accessible

  • It relies on a HTML5 structure (dialog) plus ARIA;
  • Keyboard navigation is supported, based on ARIA Design pattern for Dialog Modal;
  • No inline CSS/JavaScript injected, your DOM stays clean, which is cool for responsive/CSP.

It’s (highly) customisable

  • You can style or animate it as you want;
  • You can create namespaces for generated classes if you need different modal styles in the same page;
  • Every aspect of the script can be customized, if you transpile the script into ES5, it will be IE9+ compatible.

Free and no license problem

  • No license problem: it uses MIT license, so it’s free, open-source and you can do whatever you want with it, including commercial use. This permission notice shall be included in all copies or substantial portions of it.
  • However, it is not prohibited to tell me that you’ve used it, or send me a little “thank you”. ;)

Lightweight

  • 18kb (development, readable by humans);
  • ~6.2kb (minified, readable by machines);
  • ~2kb minified and gzipped (readable by… mutants‽‽)

How it is working

Basically, when you activate one:

  1. the script wraps all the page into a div id="js-modal-page";
  2. adds the noscroll class on the body element (to remove scroll with CSS if needed);
  3. then inserts a dialog element at the end of your page;
  4. puts the focus into it and traps focus in the modal window;
  5. When you exit it, the focus is given back to the element that opened it.

You can close it using Esc, or by using Enter or Space if you’re on the close button.

Mouse users can click outside the modal window to close it (this option can be disabled if needed).

If you never activate a modal window, it won’t be anywhere in the code.

How to use it

Download the script

You may use npm command: npm i van11y-accessible-modal-window-aria.
You may also use bower: bower install van11y-accessible-modal-window-aria.

Option and attributes

First, put class="js-modal" on a button or a link to activate the script. Then, here are all attributes:

  • Attribute data-modal-prefix-class: will namespace all the modal CSS element classnames.
  • Attribute data-modal-text: the text of your modal window (will be put into a p tag).
  • Attribute data-modal-content-id: the id of (hidden) content in your page that will be put into your modal window (if data-modal-text is not present).
  • Attribute data-modal-title: the main title of the modal window.
  • Attribute data-modal-close-text: the text of the close button in your modal window.
  • Attribute data-modal-close-title: the title attribute of the close button in your modal window.
  • Attribute data-modal-background-click="disabled": disable the possibility to click outside the modal window to close it.
  • Attribute data-modal-close-img: a path to a valid image for the close button.
  • Attribute data-modal-focus-toid: the id of the element in the modal you want to give the focus to, when loading the modal (closing button if not specified).
  • Attribute data-modal-describedby-id: adds aria-describedby=<the value of this attribute> to the dialog tag.

If you need to close it, add class="js-modal-close" on an element in the modal content, it will trigger a click on close button.

Remember there are some demos, it will be easier to understand: Demo of accessible modal window

The script is launched when the page is loaded. If you need to execute it on AJAX-inserted content, you may use for example on <div id="newContent">your modal source</div>:

van11yAccessibleModalWindowAria(document.getElementById('newContent')[, addListeners]);
addListeners is a facultative boolean (by default set to true) to add modal listeners (should be set up only the first time in most of the cases).

Minimal styling classes

Here is the minimal set of styles needed to make it work (without data-modal-prefix-class attribute):

/* needed for old browsers */
dialog {
  display: block;
  border: 0;
}
/* removes scroll when modal is opened */
.no-scroll {
  overflow: hidden;
}
/* overlay covers everything */
.modal-overlay {
  position: fixed;
  top: 0;
  bottom: 0;
  right: 0;
  left: 0;
  z-index: 666;
}
/* modal */
.modal {
  position: fixed;
  left: 25%;
  right: auto;
  top: 15%;
  width: 50%;
  background: #fff;
  z-index: 667;
}

Styling classes example

Here are the styles (unprefixed) used for the demo, I’ve used data-modal-prefix-class="simple" and data-modal-prefix-class="simple-animated" to namespace elements, so each one will start with .simple-/.simple-animated-:

dialog {
  display: block;
  border: 0;
}
/* removes scroll when modal is opened */
.no-scroll {
  overflow: hidden;
}
/* overlay covers everything */
.simple-modal-overlay,
.simple-animated-modal-overlay {
  position: fixed;
  top: 0;
  bottom: 0;
  right: 0;
  left: 0;
  background: #fff;
  opacity: .8;
  z-index: 666;
  cursor: pointer;
}
.simple-modal-overlay[data-background-click="disabled"],
.simple-animated-modal-overlay[data-background-click="disabled"] {
  cursor: auto;
}
.simple-animated-modal-overlay  {
  animation: fadewhite ease .5s 1 normal ;
}

@keyframes fadewhite {
  0% {
    opacity: 0;
  }
  100% {
    opacity: .8;
  }
}
/* modal */
.simple-modal,
.simple-animated-modal {
  position: fixed;
  left: 15%;
  top: 5%;
  width: 70%;
  max-height: 98vh;
  border: 2px solid #000; 
  background: #fff;
  z-index: 667;
  padding: 2em;
  right: auto;
  overflow: auto;
}
.simple-modal-close,
.simple-animated-modal-close {
  float: right;
  background: #128197;
  border-radius: 1em;
  color: #fff;
  border: 0;
  font: inherit;
  padding: .25em .5em;
  cursor: pointer;
}
.simple-modal-close:focus,
.simple-modal-close:hover,
.simple-modal-close:active {
  outline: 1px dotted #fff;  
}
.simple-modal-close:hover,
.simple-modal-close:active {
  background: #4d287f;
}

.simple-animated-modal {
  animation: apparition ease .5s 1 normal ;
}

@keyframes apparition {
  0% {
    opacity: 0;
    max-height: 0;
    width: 0;
    left: 50%;
  }
  100% {
    opacity: 1;
    max-height: 100%;
    width: 70%;
    left: 15%;
  }
}

/* it can be easily adapted in media-queries for tablets/mobile */

/* for this example: tablets */
@media (max-width: 55.625em) {

  .simple-modal,
  .simple-animated-modal {
    left: 5%;
    top: 5%;
    height: 90%;
    width: 90%;
  }
  
}

/* for this example: mobile */
@media (max-width: 44.375em) {

  .simple-modal,
  .simple-animated-modal {
    left: 1%;
    top: 1%;
    width: 98%;
    height: 98%;
  }

}

Other style example

Here are the styles (unprefixed) used for the third example of the demo, I’ve used data-modal-prefix-class="simple-left" to namespace elements, so each one will start with .simple-left-:

/* needed for old browsers */
dialog {
  display: block;
  border: 0;
}
/* removes scroll when modal is opened */
.no-scroll {
  overflow: hidden;
}

/* another modal styling example */
/* tooltip modal for it’s easy button */
.simple-left-modal-overlay {
  position: fixed;
  top: 0;
  bottom: 0;
  right: 0;
  left: 0;
  background: #fff;
  opacity: .8;
  z-index: 666;
  cursor: pointer;
}
.simple-left-modal-overlay[data-background-click="disabled"] {
  cursor: auto;
}

.simple-left-modal-overlay {
  position: fixed;
  top: 0;
  bottom: 0;
  right: 0;
  left: 0;
  background: rgba(0, 0, 0, .8);
  opacity: .8;
  z-index: 666;
  cursor: pointer;
}

.simple-left-modal {
  left: auto;
  right: 0;
  top: 0;
  bottom: 0;
  height: 100%;
  z-index: 667;
  position: fixed;
  width: 40em;
  max-width: 100%;
  padding: 0 1em 1em 1em;
  font-size: 1em;
  border: 0;
  overflow: auto;
  background-color: #aaa ; /* fallback CSS IE9 */
  background-image:
      -webkit-linear-gradient(
        top,
        #128197 3em,
        #f7f7f7 3em
      );  background-image:
      linear-gradient(
        to bottom,
        #128197 3em,
        #f7f7f7 3em
      );
  background-attachment: local;
}
.simple-left-modal-close {
  position: absolute;
  top: .5em;
  right: 0;
  background: transparent;
  color: #fff;
  border: 0;
  cursor: pointer;
}
.simple-left-modal-title {
  color: #fff;
  font-size: 1.5em;
}