Modalist

Modalist is a powerful & lightweight (not necessarily but primarily ajaxified) modal plugin. Here is how it works:

1. You create a distinct Modalist object for every modal style.
2. You trigger a modal from your frontend code passing custom parameters
3. Modalist fetches the modal contents with AJAX while showing a loader (skippable if not desired)
4. The modal opens

Extensions

• Ruby on Rails

Table of Contents

• Usage
  • Trigger a modal
    • Asynchronous (AJAX)
    • Synchronous
  • Close a modal
  • Functions
  • Options
    • Instance
    • Trigger
  • Events
  • Advanced
    • Multiple modals
    • Fullscreen modals
    • Custom styles
• To do
• Contributing
  • Semantic Versioning

Usage

First make sure to add the necessary HTML markup to your body tag:

import Modalist from 'modalist';

document.addEventListener('DOMContentLoaded', () => Modalist.init());
document.addEventListener('modalist:render', () => Modalist.init());
let modalist = new Modalist;

@import "animate.css";
@import "modalist/src/modalist";
@import "modalist/src/themes/default";

<div class="modalist--overlay">
  <div class="modalist--loader">
    <img src="loader.png" alt="loader" />
  </div>
</div>
<div class="modalist">
  <div class="modalist--content"></div>
</div>

Trigger a modal

Let's see how to trigger modals from your HTML markup.

Learn more about opening modals from JavaScript here.

Asynchronous (AJAX)

Load modal contents from a source.

Links

The most common scenario is using a link to trigger the asynchronous opening of a modal:

<a class="modalist--trigger" href="https://jonhue.me/settings/modal">Open modal</a>

You can use data attributes to pass options customizing the modal.

Forms

When you want to open a modal after submitting a form - this is as simple as it gets:

<form id="modalist-form" action="https://jonhue.me/settings/modal" method="GET">
<!-- ... -->
<input type="submit" class="modalist--trigger" data-modalist-form="form#modalist-form" />
</form>

You can use data attributes to pass options customizing the modal.

Elements

You can also trigger a modal from any other HTML element in your view:

<div class="modalist--trigger" data-modalist-url="https://jonhue.me/settings/modal"></div>

You can use data attributes to pass options customizing the modal.

Synchronous

Use HTML markup inside .modalist--content as modal content by omitting href, data-modalist-url and data-modalist-form attributes.

<div class="modalist--trigger"></div>

Close a modal

Just add the class modalist--closer to an element. Whenever the element is the target of a click, the modal will close.

Note: Be aware that adding this class to a hyperlink or form submit button will not prevent default behavior.

Functions

let modalist = new Modalist;

// Open modal synchronously
modalist.open();

// Open modal asynchronously with a GET request
modalist.open({ url: 'https://jonhue.me/settings/modal' });

// Open modal asynchronously by submitting a form
modalist.open({ form: document.querySelector('form#modalist-form') });

// Close modal
modalist.close();

Options

Instance

Options specified when creating a new instance from the Modalist class:

let modalist = new Modalist({ transitionIn: 'fadeIn' });

• transitionIn Set the Animate.css animation name used to open a modal. Accepts a string. Defaults to fadeIn.
• transitionOut Set the Animate.css animation name used to close a modal. Accepts a string. Defaults to fadeOut.
• element Modal element node used for handling multiple-modals. Accepts a node. Defaults to document.querySelector('.modalist').

Trigger

Options specified when opening a modal instance. Can be either passed as an options hash or specified as data attributes with data-modalist- as prefix:

• url URL to fetch modal content from. Takes a string.
• form Submit a form and use the response to populate the modal. Takes a string to specify a selector for the form element.
• element Modal query selector used for handling multiple-modals. Accepts a query selector (string). Defaults to '.modalist'. Can only be used as a data attribute.

Events

Modalist emits events that allow you to track the navigation lifecycle and respond to content loading. Modalist fires events on the document object.

• modalist:click fires when you click a Modalist enabled element to trigger a modal opening. Access the clicked element with event.data.element. Access the requested location with event.data.url or the form element to be submitted with event.data.form.

• modalist:request-start fires before Modalist issues a network request to fetch the modal content.

• modalist:request-end fires after the network request completes.

• modalist:before-render fires before rendering the content.

• modalist:render fires after Modalist renders the content in the modal.

• modalist:load fires after Modalist completed preparing the modal and started opening it.

• modalist:close fires before Modalist closes the modal.

Advanced

Multiple modals

Modalist allows you to use multiple elements as modals:

let firstModal = new Modalist({ element: document.querySelector('#first-modal') });
let secondModal = new Modalist({ element: document.querySelector('#second-modal') });

<div class="modalist" id="first-modal">
    <!-- ... -->
</div>
<div class="modalist" id="second-modal">
    <!-- ... -->
</div>

Note: You only need to add the modalist--overlay element once.

Now just use the instance to call Modalist functions. You can specify the data-modalist-element attribute on you trigger elements to be able to trigger a specific modal directly from your HTML markup:

<a class="modalist--trigger" href="https://jonhue.me/settings/modal" data-modalist-element="#first-modal">Open first modal</a>

Fullscreen modals

Add the modalist--full-screen class to your modals to make them full screen.

Custom styles

You can include a custom version of the default Modalist theme in your project. Customizing the main styles is not advised.

To do

We use GitHub projects to coordinate the work on this project.

To propose your ideas, initiate the discussion by adding a new issue.

Contributing

We hope that you will consider contributing to Modalist. Please read this short overview for some information about how to get started:

Learn more about contributing to this repository, Code of Conduct

Semantic Versioning

Modalist follows Semantic Versioning 2.0 as defined at http://semver.org.