The simplest possible modal for jQuery


A simple & lightweight method of displaying modal windows with jQuery.

For quick examples and demos, head to

Why another modal plugin?

Most plugins I've found try to do too much, and have specialized ways of handling photo galleries, iframes and video. The resulting HTML & CSS is often bloated and difficult to customize.

By contrast, this plugin handles the two most common scenarios I run into

  • displaying an existing DOM element
  • loading a page with AJAX

and does so with as little HTML & CSS as possible.


You can install jquery-modal with npm:

npm install jquery-modal

or with Bower:

bower install jquery-modal

or use the hosted version from cdnjs:

<!-- Remember to include jQuery :) -->
<script src=""></script>

<!-- jQuery Modal -->
<script src=""></script>
<link rel="stylesheet" href="" />

Using Rails? Check out the jquery-modal-rails plugin!

jQuery Requirements: As of version 0.3.0, jQuery 1.7 is required. If you're using an earlier version of jQuery you can use the v.0.2.5 tag.

Naming conflict with Bootstrap: Bootstrap's modal uses the same $.modal namespace. If you want to use jquery-modal with Bootstrap, the simplest solution is to manually modify the name of this plugin.


Method 1: Automatically attaching to links

The simplest approach is to add rel="modal:open" to your links and use the href attribute to specify what to open in the modal.

Open an existing DOM element by ID:

<form id="login-form" class="modal">

<a href="#login-form" rel="modal:open">Login</a>

Load a remote URL with AJAX:

<a href="login.html" rel="modal:open">Login</a>

Method 2: Manually

You can manually open a modal by calling the .modal() method on the element:

<form id="login-form" class="modal">

You can also invoke .modal() directly on links:

<a href="#ex5" data-modal>Open a DOM element</a>
<a href="ajax.html" data-modal>Open an AJAX modal</a>
$('a[data-modal]').click(function(event) {
  return false;

Compatibility Fallback

You can provide a clean fallback for users who have JavaScript disabled by manually attaching the modal via the data-modal attribute. This allows you to write your links pointing to the href as normal (fallback) while enabling modals where JavaScript is enabled.

<!-- By default link takes user to /login.html -->
<a href="/login.html" data-modal="#login-modal">Login</a>

<!-- Login modal embedded in page -->
<div id="login-modal" class="modal">

<!-- For browsers with JavaScript, open the modal. -->
  $(function() {
    $('a[data-modal]').on('click', function() {
      return false;

Fade Transitions

By default the overlay & window appear instantaneously, but you can enable a fade effect by specifying the fadeDuration option.

$('').click(function(event) {
    fadeDuration: 250
  return false;

This will fade in the overlay and modal over 250 milliseconds simultaneously. If you want the effect of the overlay appearing before the window, you can specify the fadeDelay option. This indicates at what point during the overlay transition the window transition should begin.

So if you wanted the window to fade in when the overlay's was 80% finished:

  fadeDuration: 250,
  fadeDelay: 0.80

Or, if you wanted the window to fade in a few moments after the overlay transition has completely finished:

  fadeDuration: 250,
  fadeDelay: 1.5

The fadeDelay option only applies when opening the modal. When closing the modal, both the modal and the overlay fade out simultaneously according to the fadeDuration setting.

Fading is the only supported transition.


Because there can be only one modal active at a single time, there's no need to select which modal to close:


Similar to how links can be automatically bound to open modals, they can be bound to close modals using rel="modal:close":

<a href="#close" rel="modal:close">Close window</a>

(Note that modals loaded with AJAX are removed from the DOM when closed).

Checking current state

  • Use $.modal.isActive() to check if a modal is currently being displayed.
  • Use $.modal.getCurrent() to retrieve a reference to the currently active modal instance, if any.


These are the supported options and their default values:

$.modal.defaults = {
  closeExisting: true,    // Close existing modals. Set this to false if you need to stack multiple modal instances.
  escapeClose: true,      // Allows the user to close the modal by pressing `ESC`
  clickClose: true,       // Allows the user to close the modal by clicking the overlay
  closeText: 'Close',     // Text content for the close <a> tag.
  closeClass: '',         // Add additional class(es) to the close <a> tag.
  showClose: true,        // Shows a (X) icon/link in the top-right corner
  modalClass: "modal",    // CSS class added to the element being displayed in the modal.
  blockerClass: "modal",  // CSS class added to the overlay (blocker).

  // HTML appended to the default spinner during AJAX requests.
  spinnerHtml: '<div class="rect1"></div><div class="rect2"></div><div class="rect3"></div><div class="rect4"></div>',

  showSpinner: true,      // Enable/disable the default spinner during AJAX requests.
  fadeDuration: null,     // Number of milliseconds the fade transition takes (null means no transition)
  fadeDelay: 1.0          // Point during the overlay's fade-in that the modal begins to fade in (.5 = 50%, 1.5 = 150%, etc.)


The following events are triggered on the modal element at various points in the open/close cycle (see below for AJAX events).

$.modal.BEFORE_BLOCK = 'modal:before-block';    // Fires just before the overlay (blocker) appears.
$.modal.BLOCK = 'modal:block';                  // Fires after the overlay (block) is visible.
$.modal.BEFORE_OPEN = 'modal:before-open';      // Fires just before the modal opens.
$.modal.OPEN = 'modal:open';                    // Fires after the modal has finished opening.
$.modal.BEFORE_CLOSE = 'modal:before-close';    // Fires when the modal has been requested to close.
$.modal.CLOSE = 'modal:close';                  // Fires when the modal begins closing (including animations).
$.modal.AFTER_CLOSE = 'modal:after-close';      // Fires after the modal has fully closed (including animations).

The first and only argument passed to these event handlers is the modal object, which has four properties:

modal.$elm;       // Original jQuery object upon which modal() was invoked.
modal.options;    // Options passed to the modal.
modal.$blocker;   // The overlay element.
modal.$anchor;    // Anchor element originating the event.

So, you could do something like this:

$('#purchase-form').on($.modal.BEFORE_CLOSE, function(event, modal) {


Basic support

jQuery Modal uses $.get for basic AJAX support. A simple spinner will be displayed by default (if you've included modal.css) and will have the class modal-spinner. If you've set the modalClass option, the spinner will be prefixed with that class name instead.

You can add text or additional HTML to the spinner with the spinnerHtml option, or disable the spinner entirely by setting showSpinner: false.

The default spinner is from the excellent SpinKit by Tobias Ahlin 👍


The following events are triggered when AJAX modals are requested.

$.modal.AJAX_SEND = 'modal:ajax:send';
$.modal.AJAX_SUCCESS = 'modal:ajax:success';
$.modal.AJAX_FAIL = 'modal:ajax:fail';
$.modal.AJAX_COMPLETE = 'modal:ajax:complete';

The handlers receive no arguments. The events are triggered on the <a> element which initiated the AJAX modal.

More advanced AJAX handling

It's a good idea to provide more robust AJAX handling -- error handling, in particular. Instead of accommodating the myriad $.ajax options jQuery provides, jquery-modal makes it possible to directly modify the AJAX request itself.

Simply bypass the default AJAX handling (i.e.: don't use rel="modal")

<a href="ajax.html" rel="ajax:modal">Click me!</a>

and make your AJAX request in the link's click handler. Note that you need to manually append the new HTML/modal in the success callback:

$('a[rel="ajax:modal"]').click(function(event) {


    url: $(this).attr('href'),

    success: function(newHTML, textStatus, jqXHR) {

    error: function(jqXHR, textStatus, errorThrown) {
      // Handle AJAX errors

    // More AJAX customization goes here.


  return false;

Note that the AJAX response must be wrapped in a div with class modal when using the second (manual) method.

Bugs & Feature Requests

Found a bug? MEH!

Just kidding. Please create an issue and include a publicly-accessible demonstration of the bug. Dropbox or JSFiddle work well for demonstrating reproducable bugs, but you can use anything as long as it's publicly accessible. Your issue is much more likely to be resolved/merged if it includes a fix & pull request.

Have an idea that improves jquery-modal? Awesome! Please fork this repository, implement your idea (including documentation, if necessary), and submit a pull request.

I don't use this library as frequently as I used to, so if you want to see a fix/improvement you're best off submitting a pull request. Bugs without a test case and/or improvements without a pull request will be shown no mercy and closed!


Maintainers Wanted

This library became more popular and active than I ever expected, and unfortunately I don't have time to maintain it myself.

If you are interested in helping me maintain this library, please let me know — I would love your help!

Read more about becoming a maintainer »

I'd especially like people who would be excited about working towards a brand new jQuery Modal 2.0. See my Proposal for jQuery Modal 2.0 for more details & discussion.

How to contribute

I welcome improvements to this plugin, particularly with:

  • Performance improvements
  • Making the code as concise/efficient as possible
  • Bug fixes & browser compatibility

Please fork and send pull requests, or create an issue. Keep in mind the spirit of this plugin is minimalism so I'm very picky about adding new features.

Tips for development/contributing

  • Make sure dependencies are installed: npm install
  • After modifying jquery.modal.js and/or jquery.modal.css, you can optionally regenerate the minified files with gulp min and gulp css respectively.
  • Make sure you have updated documentation ( and/or examples/index.html) if necessary. Pull requests without documentation updates will be rejected.
  • Maintainers should increment version numbers and run gulp changelog when cutting a new release.


Please post a question on StackOverflow. Commercial support by email is also available — please contact [email protected] for rates. Unfortunately I am unable to provide free email support.

License (MIT)

jQuery Modal is distributed under the [MIT License](Learn more at

Copyright (c) 2012 Kyle Fox

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

  • width of the modal window.

    width of the modal window.

    I can't resize the width of the modal. I'm using rails and I have:

    <%= link_to "Istruzioni", instructions_path, :rel => "modal:open", :id => "#istruzioni_modal" %>

    in the css I have:

    istruzioni_modal { width: 700px; }

    but the modal window is not resized.

    opened by ghost 13
  • AJAX calls don't show modal until request is complete

    AJAX calls don't show modal until request is complete

    Would be nice if the modal would show right away (with a spinner or something) to provide instant feedback to the user rather than it looking like nothing happened.

    Is this doable while still keeping things nice and simple? Loving the simplicity of this lib, by the way :)

    opened by bensie 13
  • New: allow multiple modals (fix #101)

    New: allow multiple modals (fix #101)

    Here's a code change proposal to allow multiple modals to be opened at the same time (#101).

    In short:

    • the current variable is replaced by a modals array
    • a new unique option is introduced, which determines if the new modal should be unique or not (i.e if existing modals should be closed or not). This option defaults to true, in order to keep backwards compatibility
    • only one blocker is used for any number of modals
    • the front modal gets the current class while the other ones get the behind class, thus allowing any styling for the modals in background

    A test demo is visible here.

    NB: if you're interested in this change, as well as the one suggested in #110, you might be interested by the merging result of those two, which I prepared as well (I needed it for a project).

    opened by xfra35 12
  • Refactor: wrap .modal in .blocker (fix #69)

    Refactor: wrap .modal in .blocker (fix #69)


    First of all thanks for sharing that plugin. It's light and functional, and that's all we need :)

    The only blocking issue is the inability to scroll overflowing content (#69).

    @alexgalli (#67) and @pawel-piskorz (#75) suggested two approaches to fix it, which both have the advantage of being simple and backward compatible. They also have some drawbacks:

    • with #67, scrollbars may easily break the modal design
    • with #75, scrolling the modal also scrolls the body behind

    Here's a third approach, so that you can make your choice ;)

    This approach is the one you've been described here. It works well with overflowing content, but it has the disadvantage to break a few things and thus, not to be backward compatible. Here's the list of changes:

    1. .modal is wrapped inside .blocker
    2. .modal is horizontally and vertically centered using CSS (cf. the ghost technique described here)
    3. overflow: hidden is applied to the document body when the modal is displayed

    Here are the consequences of those changes:

    • .blocker can't be styled in JS only, because of the ghost technique. So it has to appear in the plugin stylesheet. Also, we can't apply opacity on it anymore, now that it contains the modal, so this has to be replaced with CSS rgba(). That also means we can drop the overlay and opacity options.
    • since centering is performed using CSS instead of JS, the plugin will probably fail to work on IE<8. That also mean the center() method can be dropped.

    If you decide to go with this solution, some extra cleanup should follow (mainly remove center(), overlay and opacity from the docs and the examples). I can take care of it if you need.

    opened by xfra35 12
  • Naming conflict with bootstrap

    Naming conflict with bootstrap

    I ran into the same issue #33 was having. I was getting a grey, unclickable background but the modal wouldn't show.

    The problem seems to be the name of the plugin because it runs into a naming conflict with Bootstrap! So I replaced every occurrence of the word "modal" with "jmodal" in the plugin and now it works as expected.

    I suggest using another variable for the global namespace, since bootstrap is widely used.

    P.S.: I opened a new issue so people using bootstrap will find the solution faster.

    opened by a1ee9b 12
  • Avoid having to set inline styles to hide modal by default

    Avoid having to set inline styles to hide modal by default

    I have just started using this and everything was working fine, but then noticed the modal was showing on the page by default (right down the bottom); shouldn't the modal be hidden by default!?

    This is caused by the display: inline-block; style in the .modal class.

    I tried fiddling around a bit but nothing seems to work perfectly unless you set an inline-style for the element with the .modal class to display: none;.

    This is a great modal script, but having to manually set an inline-style on every modal you have isn't so great.

    Apologies if you don't have to do this and I'm doing something wrong here, but I checked your examples page and that's how you were doing it as well.

    opened by cyphix333 10
  • New Option: add additional css class(es) to close link

    New Option: add additional css class(es) to close link

    I know your intentions are to keep this as absolutely simple as possible, but I'd love the ability to add a custom class to the close button.

    This way custom CSS can be written to override the default look for the close button, including the ability to utilize icon fonts. This is especially handy if they are already being used in the project at hand (which, for me, nowadays is almost always.)

    This pull represents the simplest implementation of this feature that I could think of, leaving the styles completely up to the user.

    An example has been added to the demo, and the README has been updated as well.

    opened by christiannaths 10
  • Spinner code

    Spinner code

    • Spinner is not optional for ajax requests.
    • Spinner uses a css class .modal-spinner which by default adds a spinner background image but if you want to show text or HTML, you can use the $.modal.defaults.spinnerHtml option.
    • If AJAX get request fails, the spinner is closed and the modal will not appear.
    opened by adiospace 10
  • Modal is behind the blocker.

    Modal is behind the blocker.

    Triggering the modal via javascript is putting content behind the curtain (not in front as it was supposed to). This looks like a problem with z-indexs.

    How can I fix this?

    opened by pr7vinas 9
  • Add fade in/fade out effect

    Add fade in/fade out effect

    Hi, it is possible to add an option to fade in and fade out the modal instead of instantly showing and hiding it?

    The instant show/hide is good for some scenarios but for others a 'transition' is better. To a lot of non-web people it take some time to figure out why all the screen is suddenly 'kind of black' and that a modal just opened. A 400 ms transition can fix this problem!


    opened by jonagoldman 9
  • Cannot get select2 dropdown working correctly in modal

    Cannot get select2 dropdown working correctly in modal


    I am trying to get the jQuery plugin select2 working correctly within a modal, however because I have the modal set to display: none to start with I need to reinitialize select2.

    Let me note that it works fine if I don't hide the modal by default, but obviously you need to.

    So I tried this code:

    $('.modal').on('modal:open', function(e){

    However it didn't seem to work; I can destroy it fine, so it's getting the instance, but it's failing to resize itself properly, which tells me the select is still hidden when it attempts to reinitialize - but this sppears to be the most relevant event for what I need to do?

    Implementation Issue 
    opened by cyphix333 8
  • BEFORE_CLOSE Event doesnt seem to fire? Want to stop iframe on modal close

    BEFORE_CLOSE Event doesnt seem to fire? Want to stop iframe on modal close

    Hi There,

    Have been trying many things but can't get this event to fire?


    $('iframe').on($.modal.BEFORE_CLOSE , function (event, modal) { var video = $("iframe").attr("src"); $("iframe").attr("src",""); $("iframe").attr("src",video); console.log('test'); });

    opened by AgitateCurtis 0
  • Trouble Displaying an iFrame

    Trouble Displaying an iFrame


    I am developing an application that uses Square to process user payments. In order to accomplish the payment processing my app displays a UI that my app obtains from the Square server, This Square UI takes the form of an iframe that allows the user to interact directly with the Square server in order to provide credit card information.

    If I display the Square UI directly on my page then all is good. See the "SquarePaymentProcessing" screen shot.

    However, if I display the Square UI in a jquery-modal popup then it does not render, even though the other elements that my application adds to the jquery-modal popup (such as the Submit Payment button) do appear properly. See the "SquarePaymentProcessingJqueryModal" screen shot wherein significant information is being displayed in the JavaScript Console (I added a red border to the Square UI).

    If you folks cannot offer me any other help then at least please tell me this: Should I have an expectation that jquery-modal is capable of displaying an iframe?

    Thank you for your consideration.

    SquarePaymentProcessing SquarePaymentProcessingJqueryModal
    opened by verticon 6
  • Close a specific modal popup, by providing the element Id

    Close a specific modal popup, by providing the element Id

    Hi, I need to know if there is way to close a specific modal pop up, by providing the html element id as an argument to $.modal.close()

    Kindly help me with that!

    opened by selvarajan31 1
  • mouseUp on overlay is closing modal

    mouseUp on overlay is closing modal

    Recently I was selecting some text on a modal and ended up with the mouse cursor outside the modal. To my surprise, this closed the modal! You can test this behavior on the first example on the jQuery modal website:


    In my eyes this is an undesired behavior, and it could be easily fixed by changing the following code (line 100 on jquery.modal.js):

    if (this.options.clickClose)
            this.$ {
              if ( === this)

    with something like this:

    if (this.options.clickClose) {
        if (!this.$ {
            this.$ = {};
        this.$ = false;
        this.$'mousedown').on('mousedown', function (e) {
            if ( === this){
                m.$ = true;
        this.$'mouseup').on('mouseup', function (e) {
            if ( === this && m.$ {
            } else {
                m.$ = false;

    My code isn't very elegant but does the trick.

    opened by VascoRatoFCCN 0
  • AJAX loaded modal not being removed from DOM on close

    AJAX loaded modal not being removed from DOM on close

    When modals are opened using <a rel='modal:open'...>, they are removed from the DOM when the modal is closed. This does not happen is the modal is loaded via AJAX per the examples here.

    // Open modal in AJAX callback
    $('#manual-ajax').click(function(event) {
      this.blur(); // Manually remove focus from clicked link.
      $.get(this.href, function(html) {

    Please consider removing the modal from the DOM when it is closed the same way that it is removed when launched from a hyperlink.

    I have fixed this and tested - will submit a PR, but not sure if this project still has active maintainers?

    opened by vanboom 0
jBox is a jQuery plugin that makes it easy to create customizable tooltips, modal windows, image galleries and more.

jBox jBox is a jQuery plugin that makes it easy to create customizable tooltips, modal windows, image galleries and more. Demo: https://stephanwagner.

Stephan Wagner 1.4k Dec 15, 2022
Elegant, responsive, flexible and lightweight modal plugin with jQuery.

iziModal Elegant, responsive, flexible and lightweight modal plugin with jQuery. Fast Responsive Animated Lightweight Custom

Marcelo Dolza 2.1k Dec 30, 2022
Extends the default Bootstrap Modal class. Responsive, stackable, ajax and more.

Note: Since this plugin was created to solve a lot of the issues with BS2, it still uses the BS2 markup syntax. Currently I believe the default BS3 mo

Jordan Schroter 5k Dec 28, 2022
A modal built with pure CSS, enhanced with JavaScript

CSS Modals Modals built out of pure CSS Please visit the website to read more about this project and refer to the FAQ in case of a question. What is i

Hans Christian Reinl 1.8k Dec 22, 2022
Simple to use modal / alert / dialog / popup. Created with vanilla JS. No javascript knowledge required! Works on every browser and device! IE9

EinsModal The last modal / alert / dialog you will ever need! Full Documentation: EinsModal is the best solution to inte

EinsCMS 30 Oct 20, 2022
A simple vanilla and lightweight modal which is easy to expand

A simple vanilla and lightweight modal which is easy to expand

null 1 Jul 3, 2022
Toggle the state of a UI element to easily create components e.g. collapse, accordion, tabs, dropdown, dialog/modal.

Tiny UI Toggle Toggle the state of a UI element to easily create components e.g. collapse, accordion, tabs, dropdown, dialog/modal. Demo and documenta

Nigel O Toole 79 Dec 22, 2022
jQuery PopBox UI Element

jQuery PopBox jQuery PopBox is a simple balloon UI element inspired by 37Signals Highrise CRM. See it in action here:

Gristmill 427 Sep 24, 2022
A light-weight, customizable lightbox plugin for jQuery

About Colorbox: A customizable lightbox plugin for jQuery. See the project page for documentation and a demonstration, and the FAQ for solutions and e

Jack Moore 4.8k Dec 29, 2022
jQuery lightbox script for displaying images, videos and more. Touch enabled, responsive and fully customizable.

fancyBox jQuery lightbox script for displaying images, videos and more. Touch enabled, responsive and fully customizable. See the project page for doc

Jānis Skarnelis 7.2k Jan 2, 2023
A touchable jQuery lightbox

Swipebox A touchable jQuery lightbox. View project page What is Swipebox ? Swipebox is a jQuery "lightbox" plugin for desktop, mobile and tablet. Feat

null 2k Dec 6, 2022
A Lightweight Responsive jQuery Tooltip Plugin

tipso A Lightweight Responsive jQuery Tooltip Plugin There is also a Wordpress version of this plugin. Get it here Getting started Include jQuery <scr

Bojan Petkovski 325 Dec 21, 2022
This is the simplest possible nodejs api using express.

NodeJS JWT Authentication sample A Todo Application with NodeJS and ExpressJS that uses JWT authentication to manage each user's todos. Available APIs

Yacine Maouche 3 Sep 11, 2022
⚡️The Fullstack React Framework — built on Next.js

The Fullstack React Framework "Zero-API" Data Layer — Built on Next.js — Inspired by Ruby on Rails Read the Documentation “Zero-API” data layer lets y

⚡️Blitz 12.5k Jan 4, 2023
Lightweight vanilla js modal component (just 2kb) , pure javascript Modal

Lightweight vanilla js modal component (just 2kb) pure javascript Modal , This is just 2kb Lightweight vanilla js modal component with zero dependenci

Salah Eddine Lalami 12 Dec 12, 2022
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
The simplest yet effective jQuery idle plugin

jquery.inactivity The simplest yet effective jQuery idle (inactivity) plugin Download Uncompressed Compressed Purpose Listen for mouse, keyboard, touc

Alexandros 11 Oct 18, 2022
Avgrund is jQuery plugin with new modal concept for popups

Avgrund Avgrund is a jQuery plugin for your modal boxes and popups. It uses new concept showing depth between popup and page. It works in all modern b

Dmitri Voronianski 1.8k Dec 14, 2022