{"id":13826572,"url":"https://github.com/kylefox/jquery-modal","last_synced_at":"2025-05-13T23:05:47.185Z","repository":{"id":1076719,"uuid":"919555","full_name":"kylefox/jquery-modal","owner":"kylefox","description":"The simplest possible modal for jQuery","archived":false,"fork":false,"pushed_at":"2024-04-18T03:52:43.000Z","size":301,"stargazers_count":2619,"open_issues_count":73,"forks_count":664,"subscribers_count":73,"default_branch":"master","last_synced_at":"2025-04-30T07:45:06.861Z","etag":null,"topics":["dialog","javascript","jquery","jquery-modal","modal","modal-plugin"],"latest_commit_sha":null,"homepage":"http://jquerymodal.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylefox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-09-17T22:16:41.000Z","updated_at":"2025-04-18T13:59:36.000Z","dependencies_parsed_at":"2024-05-04T05:33:50.882Z","dependency_job_id":"382a5dc2-4383-4bc6-a0ef-ba8cea8bb848","html_url":"https://github.com/kylefox/jquery-modal","commit_stats":{"total_commits":202,"total_committers":32,"mean_commits":6.3125,"dds":0.6287128712871287,"last_synced_commit":"a8b9c9b01961c0a3c6676fcc8fe6cc5b8c74cb5c"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylefox%2Fjquery-modal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylefox%2Fjquery-modal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylefox%2Fjquery-modal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylefox%2Fjquery-modal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylefox","download_url":"https://codeload.github.com/kylefox/jquery-modal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254040711,"owners_count":22004598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dialog","javascript","jquery","jquery-modal","modal","modal-plugin"],"created_at":"2024-08-04T09:01:40.506Z","updated_at":"2025-05-13T23:05:42.175Z","avatar_url":"https://github.com/kylefox.png","language":"JavaScript","readme":"A simple \u0026 lightweight method of displaying modal windows with jQuery.\n\nFor quick examples and demos, head to [jquerymodal.com](http://jquerymodal.com/).\n\n# Why another modal plugin?\n\nMost plugins I've found try to do too much, and have specialized ways of handling photo galleries, iframes and video.  The resulting HTML \u0026 CSS is often bloated and difficult to customize.\n\nBy contrast, this plugin handles the two most common scenarios I run into\n\n* displaying an existing DOM element\n* loading a page with AJAX\n\nand does so with as little HTML \u0026 CSS as possible.\n\n# Installation\n\nYou can install [jquery-modal](https://www.npmjs.com/package/jquery-modal) with npm:\n\n`npm install jquery-modal`\n\nor with [Bower](http://bower.io/):\n\n`bower install jquery-modal`\n\nor use the hosted version from [cdnjs](https://cdnjs.com/libraries/jquery-modal):\n\n```html\n\u003c!-- Remember to include jQuery :) --\u003e\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0/jquery.min.js\"\u003e\u003c/script\u003e\n\n\u003c!-- jQuery Modal --\u003e\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/jquery-modal/0.9.2/jquery.modal.min.js\"\u003e\u003c/script\u003e\n\u003clink rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/jquery-modal/0.9.2/jquery.modal.min.css\" /\u003e\n```\n\n**Using Rails?** Check out the [jquery-modal-rails plugin](https://github.com/dei79/jquery-modal-rails)!\n\n**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.](https://github.com/kylefox/jquery-modal/tags)\n\n**Naming conflict with Bootstrap:** Bootstrap's [modal](http://getbootstrap.com/javascript/#modals) 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.\n\n# Opening\n\n#### Method 1: Automatically attaching to links\n\nThe simplest approach is to add `rel=\"modal:open\"` to your links and use the `href` attribute to specify what to open in the modal.\n\nOpen an existing DOM element by ID:\n\n```html\n\u003cform id=\"login-form\" class=\"modal\"\u003e\n  ...\n\u003c/form\u003e\n\n\u003ca href=\"#login-form\" rel=\"modal:open\"\u003eLogin\u003c/a\u003e\n```\n\nLoad a remote URL with AJAX:\n\n```html\n\u003ca href=\"login.html\" rel=\"modal:open\"\u003eLogin\u003c/a\u003e\n```\n\n#### Method 2: Manually\n\nYou can manually open a modal by calling the `.modal()` method on the element:\n\n```html\n\u003cform id=\"login-form\" class=\"modal\"\u003e\n  ...\n\u003c/form\u003e\n```\n\n```js\n$('#login-form').modal();\n```\n\nYou can also invoke `.modal()` directly on links:\n\n```html\n\u003ca href=\"#ex5\" data-modal\u003eOpen a DOM element\u003c/a\u003e\n\u003ca href=\"ajax.html\" data-modal\u003eOpen an AJAX modal\u003c/a\u003e\n```\n\n```js\n$('a[data-modal]').click(function(event) {\n  $(this).modal();\n  return false;\n});\n```\n\n### Compatibility Fallback\n\nYou 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.\n\n```html\n\u003c!-- By default link takes user to /login.html --\u003e\n\u003ca href=\"/login.html\" data-modal=\"#login-modal\"\u003eLogin\u003c/a\u003e\n\n\u003c!-- Login modal embedded in page --\u003e\n\u003cdiv id=\"login-modal\" class=\"modal\"\u003e\n  ...\n\u003c/div\u003e\n\n\u003c!-- For browsers with JavaScript, open the modal. --\u003e\n\u003cscript\u003e\n  $(function() {\n    $('a[data-modal]').on('click', function() {\n      $($(this).data('modal')).modal();\n      return false;\n    });\n  });\n\u003c/script\u003e\n```\n\n#### Fade Transitions\n\nBy default the overlay \u0026 window appear instantaneously, but you can enable a fade effect by specifying the `fadeDuration` option.\n\n```js\n$('a.open-modal').click(function(event) {\n  $(this).modal({\n    fadeDuration: 250\n  });\n  return false;\n});\n```\n\nThis 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.\n\nSo if you wanted the window to fade in when the overlay's was 80% finished:\n\n```js\n$(elm).modal({\n  fadeDuration: 250,\n  fadeDelay: 0.80\n});\n```\n\nOr, if you wanted the window to fade in a few moments after the overlay transition has completely finished:\n\n```js\n$(elm).modal({\n  fadeDuration: 250,\n  fadeDelay: 1.5\n});\n```\n\nThe `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.\n\nFading is the only supported transition.\n\n# Closing\n\nBecause there can be only one modal active at a single time, there's no need to select which modal to close:\n\n```js\n$.modal.close();\n```\n\nSimilar to how links can be automatically bound to open modals, they can be bound to close modals using `rel=\"modal:close\"`:\n\n```html\n\u003ca href=\"#close\" rel=\"modal:close\"\u003eClose window\u003c/a\u003e\n```\n\n_(Note that modals loaded with AJAX are removed from the DOM when closed)._\n\n# Checking current state\n\n* Use `$.modal.isActive()` to check if a modal is currently being displayed.\n* Use `$.modal.getCurrent()` to retrieve a reference to the currently active modal instance, if any.\n\n# Options\n\nThese are the supported options and their default values:\n\n```js\n$.modal.defaults = {\n  closeExisting: true,    // Close existing modals. Set this to false if you need to stack multiple modal instances.\n  escapeClose: true,      // Allows the user to close the modal by pressing `ESC`\n  clickClose: true,       // Allows the user to close the modal by clicking the overlay\n  closeText: 'Close',     // Text content for the close \u003ca\u003e tag.\n  closeClass: '',         // Add additional class(es) to the close \u003ca\u003e tag.\n  showClose: true,        // Shows a (X) icon/link in the top-right corner\n  modalClass: \"modal\",    // CSS class added to the element being displayed in the modal.\n  blockerClass: \"modal\",  // CSS class added to the overlay (blocker).\n\n  // HTML appended to the default spinner during AJAX requests.\n  spinnerHtml: '\u003cdiv class=\"rect1\"\u003e\u003c/div\u003e\u003cdiv class=\"rect2\"\u003e\u003c/div\u003e\u003cdiv class=\"rect3\"\u003e\u003c/div\u003e\u003cdiv class=\"rect4\"\u003e\u003c/div\u003e',\n\n  showSpinner: true,      // Enable/disable the default spinner during AJAX requests.\n  fadeDuration: null,     // Number of milliseconds the fade transition takes (null means no transition)\n  fadeDelay: 1.0          // Point during the overlay's fade-in that the modal begins to fade in (.5 = 50%, 1.5 = 150%, etc.)\n};\n```\n\n# Events\n\nThe following events are triggered on the modal element at various points in the open/close cycle (see below for AJAX events).\n\n```javascript\n$.modal.BEFORE_BLOCK = 'modal:before-block';    // Fires just before the overlay (blocker) appears.\n$.modal.BLOCK = 'modal:block';                  // Fires after the overlay (block) is visible.\n$.modal.BEFORE_OPEN = 'modal:before-open';      // Fires just before the modal opens.\n$.modal.OPEN = 'modal:open';                    // Fires after the modal has finished opening.\n$.modal.BEFORE_CLOSE = 'modal:before-close';    // Fires when the modal has been requested to close.\n$.modal.CLOSE = 'modal:close';                  // Fires when the modal begins closing (including animations).\n$.modal.AFTER_CLOSE = 'modal:after-close';      // Fires after the modal has fully closed (including animations).\n```\n\nThe first and only argument passed to these event handlers is the `modal` object, which has four properties:\n\n```js\nmodal.$elm;       // Original jQuery object upon which modal() was invoked.\nmodal.options;    // Options passed to the modal.\nmodal.$blocker;   // The overlay element.\nmodal.$anchor;    // Anchor element originating the event.\n```\n\nSo, you could do something like this:\n\n```js\n$('#purchase-form').on($.modal.BEFORE_CLOSE, function(event, modal) {\n  clear_shopping_cart();\n});\n```\n\n# AJAX\n\n## Basic support\n\njQuery 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.\n\nYou can add text or additional HTML to the spinner with the `spinnerHtml` option, or disable the spinner entirely by setting `showSpinner: false`.\n\nThe default spinner is from the excellent [SpinKit](http://tobiasahlin.com/spinkit/) by [Tobias Ahlin](https://twitter.com/tobiasahlin) 👍\n\n## Events\n\nThe following events are triggered when AJAX modals are requested.\n\n```js\n$.modal.AJAX_SEND = 'modal:ajax:send';\n$.modal.AJAX_SUCCESS = 'modal:ajax:success';\n$.modal.AJAX_FAIL = 'modal:ajax:fail';\n$.modal.AJAX_COMPLETE = 'modal:ajax:complete';\n```\n\nThe handlers receive no arguments. The events are triggered on the `\u003ca\u003e` element which initiated the AJAX modal.\n\n## More advanced AJAX handling\n\nIt's a good idea to provide more robust AJAX handling -- error handling, in particular. Instead of accommodating the myriad [`$.ajax` options](http://api.jquery.com/jQuery.ajax/) jQuery provides, jquery-modal makes it possible to directly modify the AJAX request itself.\n\nSimply bypass the default AJAX handling (i.e.: don't use `rel=\"modal\"`)\n\n```html\n\u003ca href=\"ajax.html\" rel=\"ajax:modal\"\u003eClick me!\u003c/a\u003e\n```\n\nand 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:\n\n```js\n$('a[rel=\"ajax:modal\"]').click(function(event) {\n\n  $.ajax({\n\n    url: $(this).attr('href'),\n\n    success: function(newHTML, textStatus, jqXHR) {\n      $(newHTML).appendTo('body').modal();\n    },\n\n    error: function(jqXHR, textStatus, errorThrown) {\n      // Handle AJAX errors\n    }\n\n    // More AJAX customization goes here.\n\n  });\n\n  return false;\n});\n```\n\nNote that the AJAX response must be wrapped in a div with class \u003ccode\u003emodal\u003c/code\u003e when using the second (manual) method.\n\n# Bugs \u0026 Feature Requests\n\n### Found a bug? MEH!\n\n![](http://drops.kylefox.ca/1cqGP+)\n\n**Just kidding.** Please [create an issue](https://github.com/kylefox/jquery-modal/issues/new) and **include a publicly-accessible demonstration of the bug.** [Dropbox](https://www.dropbox.com) or [JSFiddle](http://jsfiddle.net/) 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 \u0026 pull request.\n\n**Have an idea that improves jquery-modal?** Awesome! Please fork this repository, implement your idea (including documentation, if necessary), and submit a pull request.\n\nI 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!\n\n# Contributing\n\n## Maintainers Wanted\n\n![](https://img.shields.io/badge/maintainers-wanted-red.svg)\n\nThis library became more popular and active than I ever expected, and unfortunately I don't have time to maintain it myself.\n\nIf you are interested in helping me maintain this library, please let me know — **I would love your help!**\n\n[**Read more about becoming a maintainer \u0026raquo;**](https://github.com/kylefox/jquery-modal/issues/170)\n\n_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](https://github.com/kylefox/jquery-modal/issues/169) for more details \u0026 discussion._\n\n## How to contribute\n\nI welcome improvements to this plugin, particularly with:\n\n* Performance improvements\n* Making the code as concise/efficient as possible\n* Bug fixes \u0026 browser compatibility\n\nPlease fork and send pull requests, or create an [issue](https://github.com/kylefox/jquery-modal/issues). Keep in mind the spirit of this plugin is **minimalism** so I'm very picky about adding _new_ features.\n\n## Tips for development/contributing\n\n* Make sure dependencies are installed: `npm install`\n* After modifying `jquery.modal.js` and/or `jquery.modal.css`, you can optionally regenerate the minified files with `gulp min` and `gulp css` respectively.\n* Make sure you have updated documentation (`README.md` and/or `examples/index.html`) if necessary. **Pull requests without documentation updates will be rejected.**\n* Maintainers should increment version numbers and run `gulp changelog` when cutting a new release.\n\n# Support\n\nPlease post a question on [StackOverflow](http://stackoverflow.com/). Commercial support by email is also available — please contact kylefox@gmail.com for rates. Unfortunately I am unable to provide free email support.\n\n# License (MIT)\n\njQuery Modal is distributed under the [MIT License](Learn more at http://opensource.org/licenses/mit-license.php):\n\n    Copyright (c) 2012 Kyle Fox\n\n    Permission is hereby granted, free of charge, to any person obtaining\n    a copy of this software and associated documentation files (the\n    \"Software\"), to deal in the Software without restriction, including\n    without limitation the rights to use, copy, modify, merge, publish,\n    distribute, sublicense, and/or sell copies of the Software, and to\n    permit persons to whom the Software is furnished to do so, subject to\n    the following conditions:\n\n    The above copyright notice and this permission notice shall be\n    included in all copies or substantial portions of the Software.\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\n    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\n    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\n    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":["JavaScript","Animation"],"sub_categories":["Modals and Popups"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylefox%2Fjquery-modal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylefox%2Fjquery-modal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylefox%2Fjquery-modal/lists"}