Modal

A modal is used as a dialog box that blocks the main view until the information or action required is provided.

Summary

  1. Usage
  2. Options
  3. Methods
  4. Opening a modal
  5. Modal size
  6. Static modal
  7. History option

Usage

The modal height varies according to its content, but it is limited to a max-height of 90%.
You can use a data attribute or a class name as the modal selector, as described in the example below.

You can initiate it as a jQuery plugin:

// using any selector
$('any-selector').modal(options);

or a vanilla constructor:

import Modal from 'garden/src/js/components/modal';

// using [data-modal] as the selector
new Modal(document.querySelectorAll('[data-modal]'), options);

Here is a snippet of a modal block that uses a data attribute as its selector.

<div data-modal>
  <div class="row">
    <div class="col-xs-12">
      <h2>Hello!</h2>
      <p>This is a simple modal example.</p>
    </div>
  </div>
</div>

Based on this markup, the component will get all content inside of [data-modal] and append it into .modal-body.

Note that you should not use classes such as: .modal, .modal-content, and .modal-body to initiate a modal.

Options

Modal provides some customizable options such as: container, size, triggerClose, and triggerOpen. The default values for each option are described below.

Option Default Description
container "body" A new string selector in which the modal component will be appended
size "medium" Possible values are: small, large, and medium
triggerClose null A string selector to bind and call hide method when clicked
triggerOpen null A string selector to bind and call show method when clicked
static false When false, a close icon is inserted and the hide method is called when a user clicks outside the modal
keyboard true Closes the modal when the ESC key is pressed
history false When true, the behavior of the back button is to close the modal instead of sending the user to the previous page

Below is an example on how you can pass those options to the modal component.

let options = {
  container: '.wrapper',
  size: 'small',
  triggerClose: '[data-anything]',
  triggerOpen: '[data-another-thing]',
  static: false,
  keyboard: true,
  history: true
}

// as a jquery plugin
$('[data-modal]').modal(options);

// or

// as a vanilla constructor
new Modal(document.querySelectorAll('[data-modal]'), options);

Methods

Method Description
show() Manually opens the modal and bind a close icon and the ESC key action by default
hide() Manually closes the modal and unbind the close icon and the ESC key action

Opening a modal

By default, the modal component does not provide any opening trigger element. To achieve that you can create a button, as shown in the example below.

let modal = $('[data-modal-trigger]').modal().data('modal');
let trigger = $('[data-trigger]');

trigger.on('click', () => {
  modal.show();
});

Trigger Modal example

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

To setup a default opening and closing button, you can use the triggerOpen and triggerClose options. With that, the modal will register a click event to those selectors and call show() or hide() when the click event is fired.

$('[data-modal]').modal({
  triggerClose: '.any-selector',
  triggerOpen: '[data-trigger="open"]'
});

As stated before, the modal has three predefined sizes: small, medium, or large.
Click in each button below to check each modal size.

$('[data-modal]').modal({ size: 'small|medium|large' });

Small size modal

This is an example of a small modal.

Medium size modal

This is an example of a medium modal.

Large size modal

This is an example of a large modal.

Static modal

With the static and keyboard attributes, you can turn off the options to close a modal. With that, users would have to interact with the modal before closing it.

let modalStatic = $('[data-modal-static]').modal({
  static: true,
  keyboard: false
}).data('modal');

function closeModalStatic() {
  modalStatic.hide();
}

Note that to close the modal you need to call the .hide() function manually after the user interaction.

Static Modal example

You know how to close it.

History option

With the history option activated, whenever the modal is closed, either by pressing the back button, clicking outside the modal, or in the close button, the user is sent back to the current page instead of the previous page, as it would normally behave.

The default value for this option is false, so in order to change that behavior you only need to initiate the option as true.

History modal

Now if you close the modal by pressing on the back button you will be sent to the current page instead of the previous one.

let modal = $('[data-modal]').modal({
  history: true
})