Modal

Use this class to create configurable and WAI-ARIA guidelines compliant modal dialogs. This class currently utilizes the Micromodal.js package.

The class is designed to be easy to use and does most of the heavy lifting behind the scenes. It also exposes a simple API to interact with the DOM. Some of the interactions handled by the modal include:

• 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

Note: This class is pre-installed and loaded asynchronously with Genesis out of the box.

Import the Modal extension class in your Global.js file.

// Global.js
import Modal from 'extensions/modal';

Example Usage

.mvt

First, 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.

Modal Class Attributes

It is important to note the class attributes within the example HTML structure below. These are needed for the base styling of the modals.

<!-- [1] -->
<div id="modal-1" class="g-modal" aria-hidden="true">
    <!-- [2] -->
    <div class="g-modal__overlay" tabindex="-1" data-micromodal-close>
        <!-- [3] -->
        <div class="g-modal__container" role="dialog" aria-modal="true" aria-labelledby="modal-1-title" >
            <div class="g-modal__header">
                <p id="modal-1-title" class="g-modal__title">
                    Modal Title
                </p>
                <!-- [4] -->
                <button class="g-modal__close" aria-label="Close modal" data-micromodal-close></button>
            </div>
            <div id="modal-1-content" class="g-modal__content">
                Modal Content
            </div>
        </div>
    </div>
</div>

1. This is the outermost container of the modal. Its job is to toggle the display of the modal. Every modal should have a unique id attribute. By default, the aria-hidden attribute should be set to true. The Modal class takes care of toggling the value when required.

   The container supports the following classes:

   • g-modal - Required to load in the modal base styling.
   • g-modal--slide - Add this class for animating the modal on showing and hiding actions.
   • g-modal--small - Add this class for the small modal styling.

2. This is the div which acts as the overlay for the modal. Notice the data-micromodal-close attribute 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 this attribute is removed, clicking on the overlay will not close the modal anymore.

3. The role="dialog" attribute is used to inform assistive technologies that content contained 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.

4. Ensure that all buttons have an aria-label attribute which defines the action of the button. Notice the data-micromodal-close attribute is present on the close button to close the modal on click.

Secondly, set the data-micromodal-trigger="modal-id" attribute on the actionable element, such as a button or link, where the modal should show on click. The value of this attribute should correspond to the id of the modal you wish to trigger.

Using the modal HTML structure example above with the id attribute id="modal-1", the following button example will trigger the modal display.

<button type="button" aria-label="Show modal" data-micromodal-trigger="modal-1">
    Click Me
</button>

An additional example with a link.

<a href="https://www.mydomain.com" title="Show modal" data-micromodal-trigger="modal-1">
    Click Me
</a>

Modal Options Attribute

Actionable elements may provide a data-modal-options attribute containing a JSON value correlating to a MicroModal configuration object to set the options for its target modal. This is helpful in scenarios where the target modal needs to be configured differently than the instantiated class options or the modal configuration is based dynamically off of template logic.

<button type="button" aria-label="Show modal" data-micromodal-trigger="modal-1" data-modal-options="{"disableScroll": false, "awaitCloseAnimation": true, "awaitOpenAnimation": true}">
    Click Me
</button>

.js

First, initialize the Modal class object, then call the init() class method to intialize all of the modal target elements.

Note: Any target elements using the data-modal-options attribute will have the data-micromodal-trigger attribute converted to data-micromodal-trigger-{index} based on their order in the DOM tree (ie. data-micromodal-trigger-0, data-micromodal-trigger-1, etc). These will be used as the open trigger attribute on initialization.

Preferred asynchronous initialization:

(async () => {
    const hasModalTrigger = document.querySelector(`[data-micromodal-trigger]`);

    if (!hasModalTrigger) {
        return;
    }

    const {default: Modal} = await import('extensions/modal');
    const modal = new Modal();

    modal.init();
})();

Alternatively:

import Modal from 'extensions/modal';

const modal = new Modal();

modal.init();

Modal Close Event

Modals should typically use the data-micromodal-close attribute to trigger the modal to close on click. However, sometimes modals cannot utilize an overlay but still need to close when clicking off of the modal (ie. Global Login Form). The Modal class provides an addCloseEvent() method to handle these scenarios.

The addCloseEvent() method can be called individually by passing in the modal element to target, or a list of modal ids to target can be passed to the init() method to set close events on them during initialization.

// Add close events when initializing modals
modal.init([
    'js-search-form',
    'js-global-account'
]);

// Add close event to individual modal after initialization
modal.addCloseEvent(document.getElementById('js-search-form'));

MicroModal Object

Modals can also be triggered and closed programmatically using the show and close methods on the MicroModal window object.

For example:

    import Modal from 'extensions/modal';

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

1. The string passed to the show method must correspond to the id of the modal to trigger. You can also pass in a configuration object in the show method and it will apply only to this modal. More details on the configuration object can be found below.
2. The string passed to the close method must correspond to the id of the modal to be closed.

Options

The Modal object can take an optional MicroModal configuration object for the first parameter to override any of the default configuration settings. By default, the following configuration options are set:

• awaitCloseAnimation - true
• awaitOpenAnimation - true
• disableScroll - true
• openClass - is-open

The following table defines the available configuration options:

Name	Type	Description	Default Value
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. This option will be ignored if a user's prefers-reduced-motion CSS media feature is NOT set to no-preference.	true
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. This option will be ignored if a user's prefers-reduced-motion CSS media feature is NOT set to no-preference.	true
closeTrigger	String	Custom data attribute to close modal.	data-micromodal-close
debugMode	Boolean	This option suppresses the console warnings if passed as true.	false
disableFocus	Boolean	Disable auto focus on first focusable element.	false
disableScroll	Boolean	Disables scrolling on the page while the modal is open.	true
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.	N/A
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.	N/A
openClass	String	Custom class to be applied when modal is open.	is-open
openTrigger	String	Custom data attribute to open modal.	data-micromodal-trigger