Basic Modal jQuery Plugin

A jQuery plugin for creating basic modals.

Usage

First, download and include basic-modal.jquery.js (or the minified/gzipped version) in your HTML document:

<script src="/path/to/basic-modal.jquery.js"></script>

Next, create the HTML markup for your modal:

<div id="my-modal" style="display: none;">
  <p>This is my modal content.</p>
</div>

Make sure to set the containing element to display: none; so it will be hidden by default.

Triggering the modal

There are two ways to trigger the modal.

Method 1: Data Attribute

The first way is to add a data-trigger-modal attribute to an element that, when clicked, will trigger a modal:

<a href="#" data-trigger-modal="my-modal">Trigger modal</a>

In the above example, when someone clicks on the "Trigger modal" anchor element, it will trigger the modal with an id of my-modal.

Method 2: Programmatically

The second way is to programmatically trigger the modal with an event that you define:

<!-- The element we want to trigger the modal -->
<a href="#" class="trigger-modal">Trigger modal</a>

<!-- The jQuery code to programmatically trigger the modal -->
<script>
$(function() {

  $('a.trigger-modal').on('click', function( e ) {
    e.preventDefault();
    $('#my-modal').modal();
  });

});
</script>

In the above example we're triggering a modal with an id of my-modal when someone clicks on an anchor element with a class of trigger-modal.

Options

The following are user-configurable options. How you set these options depends on which method you're using to trigger your modals (see below for examples).

Option	Default Value	Type	Description
closeModalClass	close-modal	String	The class name to give an element to close the modal on click.
animation	null	String	Animation to run when the modal is triggered. Options: 'fade' or 'slideDown'
animationDuration	400	Number	Speed of the animation.
offsetTop	null	Number	The number of pixels the modal should be offset from the top of the browser window. If no value is given, the modal will be centered vertically and horizontally.
backdropId	modal-backdrop	String	The id name of the backdrop div.
backdropAnimation	false	Boolean	If true, fades the backdrop in/out.
backdropZindex	100	Number	The z-index value of the backdrop.
backdropAnimationDuration	50	Number	The speed of the backdrop animation.
backdropClose	true	Boolean	If true, will close the modal when someone clicks outside of it.
escClose	true	Boolean	If true, will close the modal if the Esc key is pressed.

If you're using the data-attribute-modal method to trigger the modal, then you can set these options by passing a JSON array through a data-modal-options attribute on the same element:

<a href="#" data-trigger-modal="my-modal" data-modal-options='{"closeModalClass":"exit", "animation":"fade", "animationSpeed":200}'>Trigger modal</a>

Please note that JSON arrays require the use of double-quotes, so you'll need to use single-quotes around the array.

If you're programmatically triggering the modal, then you can pass the options to the modal() method:

$('#my-modal').modal({
  animation : 'slideDown',
  offsetTop : 60,
  backdropAnimation : true,
  backdropAnimationDuration : 100
})

Defaults & Styling the Modal

I've intentionally kept this plugin very basic — I didn't want to imply too much in terms of HTML markup or style — but there are some necessary defaults.

By default the resulting modal will be centered vertically and horizontally relative to the browser window. This can be overridden by providing an optional value for offsetTop, which will offset the modal n pixels from the top of the browser window (it will still center the modal horizontally, however).

A backdrop is also created by default. The backdrop ensures that the modal will be shown on top of your content and provides a click area for dismissing the modal. There are no styles implied for the backdrop, so if you want to give it a background color, for example, then you'll need to style that in your CSS.

A lot of modal plugins force an element into the modal for closing it (e.g. and anchor tag that says "Close"). I don't like this because I usually want to choose the element myself and style it accordingly. By default clicking outside of the modal or pressing the Esc key will close the modal, but you can optionally add an element to your modal with a class of close-modal (this class name itself can be overridden) that will close the modal on click. Here's an example:

<div id="my-modal" style="display: none;">
  <a href="#" class="close-modal">Close</a>
  <p>This is my modal content.</p>
</div>

License

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.