First things that you should know before you start:
You can find them in dist/ folder of GitHub repository. Sass and uncompiled JS files are in folder src/.
<!-- Core CSS file -->
<link rel="stylesheet" href="path/to/photoswipe.css">
<!-- Skin CSS file (optional)
In folder of skin CSS file there are also:
- .png and .svg icons sprite,
- preloader.gif (for browsers that do not support CSS animations) -->
<link rel="stylesheet" href="path/to/default-skin/default-skin.css">
<!-- Core JS file -->
<script src="path/to/photoswipe.min.js"></script>
<!-- UI JS file -->
<script src="path/to/photoswipe-ui-default.min.js"></script>
It doesn't matter how and where will you include JS and CSS files. Code is executed only when you call new PhotoSwipe(). So feel free to defer loading of files if you don't need PhotoSwipe to be opened initially.
PhotoSwipe also supports AMD loaders (like RequireJS) and CommonJS, use them like so:
require([
'path/to/photoswipe.js',
'path/to/photoswipe-ui-default.js'
], function( PhotoSwipe, PhotoSwipeUI_Default ) {
// var gallery = new PhotoSwipe( someElement, PhotoSwipeUI_Default ...
// gallery.init()
// ...
});
And also, you can install it via Bower (bower install photoswipe).
You can add HTML code dynamically (directly before the initialization), or have in HTML of page initially (like it's done on demo page). This code can be appended anywhere, but ideally before the closing </body>. You may reuse it across multiple galleries (as long as you use same UI class).
<!-- Root element of PhotoSwipe. Must have class pswp. -->
<div class="pswp" tabindex="-1" role="dialog" aria-hidden="true">
<!-- Background of PhotoSwipe.
It's a separate element, as animating opacity is faster than rgba(). -->
<div class="pswp__bg"></div>
<!-- Slides wrapper with overflow:hidden. -->
<div class="pswp__scroll-wrap">
<!-- Container that holds slides.
PhotoSwipe keeps only 3 slides in DOM to save memory. -->
<div class="pswp__container">
<!-- don't modify these 3 pswp__item elements, data is added later on -->
<div class="pswp__item"></div>
<div class="pswp__item"></div>
<div class="pswp__item"></div>
</div>
<!-- Default (PhotoSwipeUI_Default) interface on top of sliding area. Can be changed. -->
<div class="pswp__ui pswp__ui--hidden">
<div class="pswp__top-bar">
<!-- Controls are self-explanatory. Order can be changed. -->
<div class="pswp__counter"></div>
<button class="pswp__button pswp__button--close" title="Close (Esc)"></button>
<button class="pswp__button pswp__button--share" title="Share"></button>
<button class="pswp__button pswp__button--fs" title="Toggle fullscreen"></button>
<button class="pswp__button pswp__button--zoom" title="Zoom in/out"></button>
<!-- Preloader demo http://codepen.io/dimsemenov/pen/yyBWoR -->
<!-- element will get class pswp__preloader--active when preloader is running -->
<div class="pswp__preloader">
<div class="pswp__preloader__icn">
<div class="pswp__preloader__cut">
<div class="pswp__preloader__donut"></div>
</div>
</div>
</div>
</div>
<div class="pswp__share-modal pswp__share-modal--hidden pswp__single-tap">
<div class="pswp__share-tooltip"></div>
</div>
<button class="pswp__button pswp__button--arrow--left" title="Previous (arrow left)">
</button>
<button class="pswp__button pswp__button--arrow--right" title="Next (arrow right)">
</button>
<div class="pswp__caption">
<div class="pswp__caption__center"></div>
</div>
</div>
</div>
</div>
Order of pswp__bg, pswp__scroll-wrap, pswp__container and pswp__item elements should not be changed.
You might ask, why PhotoSwipe doesn't add this code automatically via JS, reason is simple – just to save file size, in case if you need some modification of this code.
Execute PhotoSwipe contructor. It accepts 4 arguments:
.pswp element from step 2 (it must be added to DOM).photoswipe-ui-default.js, class will be PhotoSwipeUI_Default. Can be false.var pswpElement = document.querySelectorAll('.pswp')[0];
// build items array
var items = [
{
src: 'https://placekitten.com/600/400',
w: 600,
h: 400
},
{
src: 'https://placekitten.com/1200/900',
w: 1200,
h: 900
}
];
// define options (if needed)
var options = {
// optionName: 'option value'
// for example:
index: 0 // start at first slide
};
// Initializes and opens PhotoSwipe
var gallery = new PhotoSwipe( pswpElement, PhotoSwipeUI_Default, items, options);
gallery.init();
At the end you should get something like this:
Each object in array should contain data about slide, it can be anything that you wish to display in PhotoSwipe - path to image, caption HTML string, number of shares, comments, etc.
During the navigation PhotoSwipe adds its own properties to this object (like minZoom or loaded).
var slides = [
// slide 1
{
src: 'path/to/image1.jpg', // path to image
w: 1024, // image width
h: 768, // image height
msrc: 'path/to/small-image.jpg', // small image placeholder,
// main (large) image loads on top of it,
// if you skip this parameter - grey rectangle will be displayed,
// try to use this property only when small image was loaded before
title: 'Image Caption' // used by Default PhotoSwipe UI
// if you skip it, there won't be any caption
// You may add more properties here and use them.
// For example, demo gallery uses "author" property, which is used in caption.
// author: 'John Doe'
},
// slide 2
{
src: 'path/to/image2.jpg',
w: 600,
h: 600
// etc.
}
// etc.
];
You can dynamically add more slides to this array (after PhotoSwipe is opened), e.g.:
// just push item to array
yourPhotoSwipeInstance.items.push({
src: "path/to/image.jpg",
w:1200,
h:500
});
Currently, you can not dynamically modify image of current slide, and two nearby slides, but this feature is planned.
For example, you have a list of links/thumbnails that looks like this (more info about markup of gallery):
<div class="my-gallery" itemscope itemtype="http://schema.org/ImageGallery">
<figure itemscope itemtype="http://schema.org/ImageObject">
<a href="large-image.jpg" itemprop="contentUrl" data-size="600x400">
<img src="small-image.jpg" itemprop="thumbnail" alt="Image description" />
</a>
<figcaption itemprop="caption description">Image caption</figcaption>
</figure>
<figure itemscope itemtype="http://schema.org/ImageObject">
<a href="large-image.jpg" itemprop="contentUrl" data-size="600x400">
<img src="small-image.jpg" itemprop="thumbnail" alt="Image description" />
</a>
<figcaption itemprop="caption description">Image caption</figcaption>
</figure>
</div>
... and you want click on thumbnail to open PhotoSwipe with large image (like it's done on demo page). All you need to do is:
href attribute (large image url), data-size attribute (its size), src of thumbnail, and contents of figure element (caption content).PhotoSwipe doesn't really care how will you do this. If you use framework like jQuery or MooTools, or if you don't need to support IE8, code can be simplified dramatically.
Here is pure Vanilla JS implementation with IE8 support:
var initPhotoSwipeFromDOM = function(gallerySelector) {
// parse slide data (url, title, size ...) from DOM elements
// (children of gallerySelector)
var parseThumbnailElements = function(el) {
var thumbElements = el.childNodes,
numNodes = thumbElements.length,
items = [],
figureEl,
linkEl,
size,
item;
for(var i = 0; i < numNodes; i++) {
figureEl = thumbElements[i]; // <figure> element
// include only element nodes
if(figureEl.nodeType !== 1) {
continue;
}
linkEl = figureEl.children[0]; // <a> element
size = linkEl.getAttribute('data-size').split('x');
// create slide object
item = {
src: linkEl.getAttribute('href'),
w: parseInt(size[0], 10),
h: parseInt(size[1], 10)
};
if(figureEl.children.length > 1) {
// <figcaption> content
item.title = figureEl.children[1].innerHTML;
}
if(linkEl.children.length > 0) {
// <img> thumbnail element, retrieving thumbnail url
item.msrc = linkEl.children[0].getAttribute('src');
}
item.el = figureEl; // save link to element for getThumbBoundsFn
items.push(item);
}
return items;
};
// find nearest parent element
var closest = function closest(el, fn) {
return el && ( fn(el) ? el : closest(el.parentNode, fn) );
};
// triggers when user clicks on thumbnail
var onThumbnailsClick = function(e) {
e = e || window.event;
e.preventDefault ? e.preventDefault() : e.returnValue = false;
var eTarget = e.target || e.srcElement;
// find root element of slide
var clickedListItem = closest(eTarget, function(el) {
return el.tagName === 'FIGURE';
});
if(!clickedListItem) {
return;
}
// find index of clicked item by looping through all child nodes
// alternatively, you may define index via data- attribute
var clickedGallery = clickedListItem.parentNode,
childNodes = clickedListItem.parentNode.childNodes,
numChildNodes = childNodes.length,
nodeIndex = 0,
index;
for (var i = 0; i < numChildNodes; i++) {
if(childNodes[i].nodeType !== 1) {
continue;
}
if(childNodes[i] === clickedListItem) {
index = nodeIndex;
break;
}
nodeIndex++;
}
if(index >= 0) {
// open PhotoSwipe if valid index found
openPhotoSwipe( index, clickedGallery );
}
return false;
};
// parse picture index and gallery index from URL (#&pid=1&gid=2)
var photoswipeParseHash = function() {
var hash = window.location.hash.substring(1),
params = {};
if(hash.length < 5) {
return params;
}
var vars = hash.split('&');
for (var i = 0; i < vars.length; i++) {
if(!vars[i]) {
continue;
}
var pair = vars[i].split('=');
if(pair.length < 2) {
continue;
}
params[pair[0]] = pair[1];
}
if(params.gid) {
params.gid = parseInt(params.gid, 10);
}
if(!params.hasOwnProperty('pid')) {
return params;
}
params.pid = parseInt(params.pid, 10);
return params;
};
var openPhotoSwipe = function(index, galleryElement, disableAnimation) {
var pswpElement = document.querySelectorAll('.pswp')[0],
gallery,
options,
items;
items = parseThumbnailElements(galleryElement);
// define options (if needed)
options = {
index: index,
// define gallery index (for URL)
galleryUID: galleryElement.getAttribute('data-pswp-uid'),
getThumbBoundsFn: function(index) {
// See Options -> getThumbBoundsFn section of documentation for more info
var thumbnail = items[index].el.getElementsByTagName('img')[0], // find thumbnail
pageYScroll = window.pageYOffset || document.documentElement.scrollTop,
rect = thumbnail.getBoundingClientRect();
return {x:rect.left, y:rect.top + pageYScroll, w:rect.width};
}
};
if(disableAnimation) {
options.showAnimationDuration = 0;
}
// Pass data to PhotoSwipe and initialize it
gallery = new PhotoSwipe( pswpElement, PhotoSwipeUI_Default, items, options);
gallery.init();
};
// loop through all gallery elements and bind events
var galleryElements = document.querySelectorAll( gallerySelector );
for(var i = 0, l = galleryElements.length; i < l; i++) {
galleryElements[i].setAttribute('data-pswp-uid', i+1);
galleryElements[i].onclick = onThumbnailsClick;
}
// Parse URL and open gallery if it contains #&pid=3&gid=1
var hashData = photoswipeParseHash();
if(hashData.pid > 0 && hashData.gid > 0) {
openPhotoSwipe( hashData.pid - 1 , galleryElements[ hashData.gid - 1 ], true );
}
};
// execute above function
initPhotoSwipeFromDOM('.my-gallery');
Example on CodePen (focus & history options are disabled due to embed issues):
Tip: you may download example from CodePen to play with it locally (Edit on CodePen -> Share -> Export .zip).
figure and figcaption elements, you may include html5shiv, or add support manually.parseThumbnailElements. PhotoSwipe is in beta, please report bugs through GitHub, suggest features on UserVoice and ask qustions through StackOverflow.
To get notified about updates follow @photoswipe on Twitter and star/watch project on GitHub.
If you think that something should be improved in this documentation page, feel free to suggest an edit on GitHub.
</> with <3 in by @dimsemenov