Project on GitHub · Build tool · Twitter of developer · Newsletter of developer
items option
{% highlight javascript %}
$.magnificPopup.open({
items: {
src: 'some-image.jpg'
},
type: 'image'
});
{% endhighlight %}
If you want to modify how the source is parsed, you may hook into the `elementParse` callback. For example:
{% highlight javascript %}
$('.image-link').magnificPopup({
type:'image',
callbacks: {
elementParse: function(item) {
// Function will fire for each target element
// "item.el" is a target DOM element (if present)
// "item.src" is a source that you may modify
console.log(item); // Do whatever you want with "item" object
}
}
});
{% endhighlight %}
## Image Type
The path to the image must be set as the main source if you selected this type. If your popup doesn't have an image source and doesn't have an image that shouldn't be preloaded (and retina-ized, etc.), use the `inline` type.
{% highlight javascript %}
image: {
markup: 'null
If window width is less than the number in this option lightbox will not be opened and the default behavior of the element will be triggered. Set to `0` to disable behavior. Option works only when you initialize Magnific Popup from DOM element.
Can also accept Function as a parameter, which should return `true` if lightbox can be opened and `false` otherwise. For example:
{% highlight javascript %}
disableOn: function() {
if( $(window).width() < 600 ) {
return false;
}
return true;
}
{% endhighlight %}
### key
null
"Key" option is a unique identifier of a single or a group of popups with the same structure. If you will not define it, DOM elements will be created and destroyed each time when you open and close popup.
You may (and should) set an equal key to different popups if their markup matches. By markup I mean options that change HTML structure of the popup (e.g. close icon placement and HTML code of it).
For example: you have many popups that show title, some text and button - you may use one key for all of them, so only one instance of this element is created. Same for popup that always contains image and caption.
You can delete cached templates like so:
// delete template with key "your-key"
delete $.magnificPopup.instance.popupsCache['your-key'];
// delete all templates
$.magnificPopup.instance.popupsCache = {};
### midClick
false
If set to `true` lightbox is opened if the user clicked on the middle mouse button, or click with Command/Ctrl key. Option works only when you initialize Magnific Popup from DOM element.
### mainClass
empty string
String that contains classes that will be added to the root element of popup wrapper and to dark overlay. For example `"myClass"`, can also contain multiple classes - `'myClassOne myClassTwo'`.
### preloader
true
Preloader in Magnific Popup is used as an indicator of current status. If option enabled, it's always present in DOM only text inside of it changes. Below you can see explanation of CSS names that are applied to container that holds preloader and content area depending on the state of current item:
{% highlight css %}
/* Content loading is in progress */
.mfp-s-loading { }
/* Content successfully loaded */
.mfp-s-ready { }
/* Error during loading */
.mfp-s-error { }
{% endhighlight %}
For example, if you want your error message to be in red add such CSS:
{% highlight css %}
.mfp-s-error .mfp-preloader {
color: red;
}
{% endhighlight %}
You can trigger change of status manually by calling `instance.updateStatus('error', 'error message')`.
### focus
empty string
String with CSS selector of an element inside popup that should be focused. Ideally it should be the first element of popup that can be focused. For example `'input'` or `'#login-input'`. Leave empty to focus the popup itself.
### closeOnContentClick
false
Close popup when user clicks on content of it. It's recommended to enable this option when you have only image in popup.
### closeOnBgClick
true
Close the popup when user clicks on the dark overlay.
### closeBtnInside
true
If enabled, Magnific Popup will put close button inside content of popup, and wrapper will get class `mfp-close-btn-in` (which in default CSS file makes color of it change). If markup of popup item is defined element with class `mfp-close` it will be replaced with this button, otherwise close button will be appended directly.
### showCloseBtn
true
Controls whether the close button will be displayed or not.
### enableEscapeKey
true
Controls whether pressing the escape key will dismiss the active popup or
not.
### modal
false
When set to `true`, the popup will have a modal-like behavior: it won't be
possible to dismiss it by usual means (close button, escape key, or
clicking in the overlay).
This is a shortcut to set ``closeOnContentClick``, ``closeOnBgClick``,
``showCloseBtn``, and ``enableEscapeKey`` to ``false``.
### alignTop
false
If set to `true` popup is aligned to top instead of to center. (basically all this option does is adds `mfp-align-top` CSS class to popup which removes styles that align popup to center).
### index
null
Used for gallery. Defines starting index. If popup is initialised from DOM element, this option will be ignored.
### fixedContentPos
auto
Popup content position. Can be `"auto"`, `true` or `false`. If set to `true` - fixed position will be used, to `false` - absolute position based on current scroll. If set to `"auto"` popup will automatically disable this option when browser doesn't support fixed position properly.
### fixedBgPos
auto
Same as an option above, but it defines position property of the dark transluscent overlay. If set to `false` - huge tall overlay will be generated that equals height of window to emulate fixed position. It's recommended to set this option to `true` if you animate this dark overlay and content is most likely will not be zoomed, as size of it will be much smaller.
### overflowY
auto
Defines scrollbar of the popup, works as overflow-y CSS property - any CSS acceptable value is allowed (e.g. `auto`, `scroll`, `hidden`). Option is applied only when fixed position is enabled.
There is no option `overflowX`, but you may easily emulate it just via CSS.
### removalDelay
0
Delay before popup is removed from DOM. Used for the [animation](#animation).
### closeMarkup
<button title="%title%" type="button" class="mfp-close">×</button>
Markup of close button. %title% will be replaced with option `tClose`.
### prependTo
document.body
The DOM element to which popup will be added. Useful when you're using ASP.NET where popup should be inside `form`. Option available since 2013/12/04.
### autoFocusLast
true
If set to `true` last focused element before popup showup will be focused after popup close. Option available since 2015/12/16.
## Gallery
The gallery module allows you to switch the content of the popup and adds navigation arrows. It can switch and mix any types of content, not just images. Gallery options:
{% highlight javascript %}
gallery: {
enabled: false, // set to true to enable gallery
preload: [0,2], // read about this option in next Lazy-loading section
navigateByImgClick: true,
arrowMarkup: '', // markup of an arrow button
tPrev: 'Previous (Left arrow key)', // title for left button
tNext: 'Next (Right arrow key)', // title for right button
tCounter: '%curr% of %total%' // markup of counter
}
{% endhighlight %}
Example:
{% highlight javascript %}
// This will create a single gallery from all elements that have class "gallery-item"
$('.gallery-item').magnificPopup({
type: 'image',
gallery:{
enabled:true
}
});
{% endhighlight %}
### Multiple galleries
To have multiple galleries on a page, you need to create a new instance of Magnific Popup for each separate gallery. For example
{% highlight html %}
{% endhighlight %}
You need to make sure that ratio of your thumbnail matches the ratio of the big image, to avoid "jumps" at the end of zoom-out animation.
2) Initialize popup with `zoom` options:
{% highlight javascript %}
// Initialize popup as usual
$('.image-link').magnificPopup({
type: 'image',
mainClass: 'mfp-with-zoom', // this class is for CSS animation below
zoom: {
enabled: true, // By default it's false, so don't forget to enable it
duration: 300, // duration of the effect, in milliseconds
easing: 'ease-in-out', // CSS transition easing function
// The "opener" function should return the element from which popup will be zoomed in
// and to which popup will be scaled down
// By defailt it looks for an image tag:
opener: function(openerElement) {
// openerElement is the element on which popup was initialized, in this case its tag
// you don't need to add "opener" option if this code matches your needs, it's defailt one.
return openerElement.is('img') ? openerElement : openerElement.find('img');
}
}
});
{% endhighlight %}
3) Optionally, add CSS fading animation to background overlay
{% highlight css %}
.mfp-with-zoom .mfp-container,
.mfp-with-zoom.mfp-bg {
opacity: 0;
-webkit-backface-visibility: hidden;
/* ideally, transition speed should match zoom duration */
-webkit-transition: all 0.3s ease-out;
-moz-transition: all 0.3s ease-out;
-o-transition: all 0.3s ease-out;
transition: all 0.3s ease-out;
}
.mfp-with-zoom.mfp-ready .mfp-container {
opacity: 1;
}
.mfp-with-zoom.mfp-ready.mfp-bg {
opacity: 0.8;
}
.mfp-with-zoom.mfp-removing .mfp-container,
.mfp-with-zoom.mfp-removing.mfp-bg {
opacity: 0;
}
{% endhighlight %}
Zoom module adds `zoomAnimationEnded` callback, which fires when zoom-in animation is finished.
## API
There is a much bigger list of public events, methods and variables than provided here which is used for module development, look inside code or type in console `$.magnificPopup.instance.` to find them, if you think that something should be added to docs - please submit commit.
### Events
You can define callbacks in `callbacks` option. Besides that, all Magnific Popup events are also dispatched using `triggerHandler` on target element (or to document if the element doesn't exist).
{% highlight javascript %}
$('.image-link').magnificPopup({
// you may add other options here, e.g.:
preloader: true,
callbacks: {
open: function() {
// Will fire when this exact popup is opened
// this - is Magnific Popup object
},
close: function() {
// Will fire when popup is closed
}
// e.t.c.
}
});
// Alternative method: using events
// Name of event should start from `mfp` and the first letter should be uppercase.
// e.g. 'open' becomes 'mfpOpen', 'beforeOpen' becomes 'mfpBeforeOpen'.
$('.image-link').on('mfpOpen', function(e /*, params */) {
console.log('Popup opened', $.magnificPopup.instance);
});
{% endhighlight %}
List of callbacks. In each callback `this` is `$.magnificPopup.instance`, so you can execute methods (`this.close()`) or access public variables (`this.currItem`).
{% highlight javascript %}
callbacks: {
beforeOpen: function() {
console.log('Start of popup initialization');
},
elementParse: function(item) {
// Function will fire for each target element
// "item.el" is a target DOM element (if present)
// "item.src" is a source that you may modify
console.log('Parsing content. Item object that is being parsed:', item);
},
change: function() {
console.log('Content changed');
console.log(this.content); // Direct reference to your popup element
},
resize: function() {
console.log('Popup resized');
// resize event triggers only when height is changed or layout forced
},
open: function() {
console.log('Popup is opened');
},
beforeClose: function() {
// Callback available since v0.9.0
console.log('Popup close has been initiated');
},
close: function() {
console.log('Popup removal initiated (after removalDelay timer finished)');
},
afterClose: function() {
console.log('Popup is completely closed');
},
markupParse: function(template, values, item) {
// Triggers each time when content of popup changes
// console.log('Parsing:', template, values, item);
},
updateStatus: function(data) {
console.log('Status changed', data);
// "data" is an object that has two properties:
// "data.status" - current status type, can be "loading", "error", "ready"
// "data.text" - text that will be displayed (e.g. "Loading...")
// you may modify this properties to change current status or its text dynamically
},
imageLoadComplete: function() {
// fires when image in current popup finished loading
// avaiable since v0.9.0
console.log('Image loaded');
},
// Only for ajax popup type
parseAjax: function(mfpResponse) {
// mfpResponse.data is a "data" object from ajax "success" callback
// for simple HTML file, it will be just String
// You may modify it to change contents of the popup
// For example, to show just #some-element:
// mfpResponse.data = $(mfpResponse.data).find('#some-element');
// mfpResponse.data must be a String or a DOM (jQuery) element
console.log('Ajax content loaded:', mfpResponse);
},
ajaxContentAdded: function() {
// Ajax content is loaded and appended to DOM
console.log(this.content);
}
}
{% endhighlight %}
### Public methods
{% highlight javascript %}
// Open popup immediately. If popup is already opened - it'll just overwite the content (but old options will be kept).
// - first parameter: options object
// - second parameter (optional): index of item to open
$.magnificPopup.open({
items: {
src: 'someimage.jpg'
},
type: 'image'
// You may add options here, they're exactly the same as for $.fn.magnificPopup call
// Note that some settings that rely on click event (like disableOn or midClick) will not work here
}, 0);
$.magnificPopup.close(); // Close popup that is currently opened (shorthand)
/*
Methods below don't have shorthand like "open" and "close".
They should be called through "instance" object.
"instance" is available only when at least one popup was opened.
For example: $.magnificPopup.instance.doSomething();
*/
var magnificPopup = $.magnificPopup.instance; // save instance in magnificPopup variable
magnificPopup.close(); // Close popup that is currently opened
// Navigation when gallery is enabled
magnificPopup.next(); // go to next item
magnificPopup.prev(); // go to prev item
magnificPopup.goTo(4); // go to item #4
magnificPopup.updateItemHTML(); // updates the popup content. Useful after you change "items" array
// Update status of popup
// First param: status type, can be: 'loading', 'error' or 'ready'.
// Second param: message that will be displayed.
magnificPopup.updateStatus('loading', 'The loading text...');
{% endhighlight %}
You may also call ANY method via `$.fn.magnificPopup('methodName' /*, param1, param2 ... */)` after you initialized the popup, for example:
{% highlight javascript %}
// First of make sure that you initialized popup on element $('.element-with-popup')
// Then
$('.element-with-popup').magnificPopup('open'); // Will open the popup
$('.element-with-popup').magnificPopup('open', 5); // Will open popup with 5th item
$('.element-with-popup').magnificPopup('next');
$('.element-with-popup').magnificPopup('goTo', 3);
{% endhighlight %}
You may also open the popup directly at initialization:
{% highlight javascript %}
$('.element-with-popup').magnificPopup({
items: {
src: 'path-to-image.jpg',
type: 'image'
}
// (optionally) other options
}).magnificPopup('open');
{% endhighlight %}
### Public properties
Most properties are available only after the popup is opened. Only most used are listed here.
{% highlight javascript %}
var magnificPopup = $.magnificPopup.instance;
magnificPopup.items // array that holds data for popup items
magnificPopup.currItem // data for current item
magnificPopup.index // current item index (integer)
magnificPopup.content // direct reference to jQuery DOM element that you open in popup
magnificPopup.bgOverlay // transluscent overlay
magnificPopup.wrap // container that holds all controls and contentContainer
magnificPopup.contentContainer // container that holds popup content, child of wrap
magnificPopup.st.el // Target clicked element that opened popup (works if popup is initialized from DOM element)
magnificPopup.st.mainEl // Main element (or collection of elements) from which popup was initialized (--''--)
magnificPopup.isIE7
magnificPopup.isIOS
{% endhighlight %}
## Translating
Internationalization of Magnific Popup is very simple, all you need is to extend default settings object with new values, or just pass options to your initialization code. If you're making some public plugin or theme, it's strongly recommended to use only second method to avoid conflicts.
Some properties contain %keys% that should not be translated, but may be reordered or removed.
{% highlight javascript %}
// Add it after jquery.magnific-popup.js and before first initialization code
$.extend(true, $.magnificPopup.defaults, {
tClose: 'Close (Esc)', // Alt text on close button
tLoading: 'Loading...', // Text that is displayed during loading. Can contain %curr% and %total% keys
gallery: {
tPrev: 'Previous (Left arrow key)', // Alt text on left arrow
tNext: 'Next (Right arrow key)', // Alt text on right arrow
tCounter: '%curr% of %total%' // Markup for "1 of 7" counter
},
image: {
tError: 'The image could not be loaded.' // Error message when image could not be loaded
},
ajax: {
tError: 'The content could not be loaded.' // Error message when ajax request failed
}
});
{% endhighlight %}
Same thing, but applied only to specific slider:
{% highlight javascript %}
$('.some-button').magnificPopup({
tClose: 'Close (Esc)',
tLoading: 'Loading...',
gallery: {
tPrev: 'Previous (Left arrow key)',
tNext: 'Next (Right arrow key)',
tCounter: '%curr% of %total%'
},
image: {
tError: 'The image could not be loaded.'
},
ajax: {
tError: 'The request failed.'
}
// surely, you may add other options here
});
{% endhighlight %}
## FAQ
### How to place gallery navigation arrows "inside" the image?
See [example on CodePen](http://codepen.io/dimsemenov/pen/JGjHK).
### How to override some function without modifying the source files?
Rewrite the function that you wish to modify by editing Magnific Popup object, you can access it like so `$.magnificPopup.instance`. For example to override function that goes to "next" item in gallery:
{% highlight javascript %}
// add this code after popup JS file is included
$.magnificPopup.instance.next = function() {
// Do something
// You may call parent ("original") method like so:
$.magnificPopup.proto.next.call(this /*, optional arguments */);
};
{% endhighlight %}
You may override any public function, just note that this change applies globally.
### How to add spinner indicator instead of "Loading..." text?
Just style element with class `.mfp-preloader`. [Example on CodePen](http://codepen.io/dimsemenov/pen/aKwxt). [Another example](http://codepen.io/dimsemenov/pen/HdjtL) (if you want to show image only after its fully loaded).
## Known issues
### When popup is opened scrollbar of window disappears and creates empty space or shifts some fixed-positioned menu (or whatever)
Solution 1: add [overflowY:'scroll'](#overflowy) option to force the scrollbar. Solution 2: use open/close popup callbacks to apply custom styling to menu that behaves incorrectly.
### Text input in [Select2](http://ivaynberg.github.io/select2/) plugin is inactive when added inside popup
Refer to [this discussion on GitHub](https://github.com/dimsemenov/Magnific-Popup/issues/280).