The Perfect Lightbox? Using PhotoSwipe with jQuery

I recently came across a JavaScript library called PhotoSwipe, and I am truly impressed. It is a brilliant library which overlays an image or a group of images on your current page, an effect popularly known as lightbox. PhotoSwipe is currently developed by Dmitry Semenov–he rebuilt it last year when he took over the project. Improvements include:

• Modular: PhotoSwipe is built into several modules, allowing you to ditch particular features you don’t need. This keeps the library very lightweight.
• Responsive: an indispensable feature by all means. Photoswipe serves the appropriate image size based on the current viewport.
• Touch gesture: PhotoSwipe supports some touch gestures which allow users to interact through Tap and Pinch, giving them pop-up, zoom, and close features.

The only downside is that PhotoSwipe won’t run out of the box. As the developer states:

“PhotoSwipe is made simple and fast for end users, not for developers. It ain't a simple jQuery plugin, at least basic JavaScript knowledge is required to install.

But it can be used in conjunction with other libraries. In this tutorial, we are going to look at how to use PhotoSwipe with jQuery. We’ll make the whole process easily comprehensible, even if you’re not well-versed in pure JavaScript.

Let’s make a start.

1. Getting Started

We’ll begin with:

1. Creating the project directories.
2. Creating an HTML document.
3. Linking to jQuery. In this tutorial I’m going to use jQuery 2.0, therefore only supporting modern browsers.
4. Grab the copies of PhotoSwipe library which comprises the files: photoswipe.min.js, photoswipe-ui-default.min.js (the code that constructs the PhotoSwipe UI), default-skin.css, default-skin.png, default-skin.svg, andpreloader.gif.
5. Arrange the files in your preferred directory order and link them within the HTML file.

2. Structuring the HTML

The HTML structure is the most essential part since it will eventually drive how we write the JavaScript. Here we will assume that we have a couple of images, as follows:

<div class="picture" itemscope itemtype="http://schema.org/ImageGallery"><figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject"><a href="img/city-1.jpg" itemprop="contentUrl" data-size="1000x667" data-index="0"><img src="img/city-1-thumb.jpg" height="400" width="600" itemprop="thumbnail" alt="Beach"></a></figure><figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject"><a href="img/city-2.jpg" itemprop="contentUrl" data-size="1000x667" data-index="1"><img src="img/city-2-thumb.jpg" height="400" width="600" itemprop="thumbnail" alt=""></a></figure></div>

Data Attributes

Aside from the class and the Schema attributes (which will help with SEO), we’ve also added a data-* attribute in the anchor tag wrapping the image. This stores the full size (width x height) of the image.

More Markup

Now we add the markup that PhotoSwipe will use to overlay the full images. Add this just before the closing body tag, </body>.

<div class="pswp" tabindex="-1" role="dialog" aria-hidden="true"><div class="pswp__bg"></div><div class="pswp__scroll-wrap"><div class="pswp__container"><div class="pswp__item"></div><div class="pswp__item"></div><div class="pswp__item"></div></div><div class="pswp__ui pswp__ui--hidden"><div class="pswp__top-bar"><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><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>

We are all set with the HTML, so now we can proceed with the JavaScript. As mentioned we will be using jQuery.

3. jQuery

Our images are grouped within a div with the picture class. There may be several more image groups within the page, hence we loop through each .picture element.

$('.picture').each( function() {
});

Details

PhotoSwipe requires us to provide the full image source along with its size. To take care of this we create a function that will loop through the anchor tag to retrieve these details, as follows:

$('.picture').each( function() {
    var $pic     = $(this),
        getItems = function() {
            var items = [];
            $pic.find('a').each(function() {
                var $href   = $(this).attr('href'),
                    $size   = $(this).data('size').split('x'),
                    $width  = $size[0],
                    $height = $size[1];

                var item = {
                    src : $href,
                    w   : $width,
                    h   : $height
                }

                items.push(item);
            });
            return items;
        }

    var items = getItems();
});

Let’s break the this code downs into several pieces:

1. We first initialize with an empty array in items = [].
2. Then we loop through each anchor tag with the .each() method.
3. $href = $(this).attr('href') obtains the value in the href attribute, storing the path of the full image.
4. $size = $(this).data('size').split('x') will obtain the value of the data-size attribute through the jQuery .data() method. We then use the the split()method to separate the value.
5. We are able to obtain the value of the width and the height separately with: $width = $size[0] and $height = $size[1].
6. Using the push() method we collect al this information in an Array.

Test in Console

We now have the image source and the image size stored in the items variable. To verify, you may run the variable through the console.log() and you should find the following data structure in the DevTools.

Click

Next, we bind the figure element with the click event, construct a PhotoSwipe instance, pass the items along with the configuration options, and finally initialize PhotoSwipe.

var $pswp = $('.pswp')[0];
$pic.on('click', 'figure', function(event) {
    event.preventDefault();
    var $index = $(this).index();
    var options = {
        index: $index,
        bgOpacity: 0.7,
        showHideOpacity: true
    }
    // Initialize PhotoSwipe
    var lightBox = new PhotoSwipe($pswp, PhotoSwipeUI_Default, items, options);
    lightBox.init();
});

The reason we use the figure element to click on, rather than the anchor tag, is so that we are able to easily retrieve the index (or the subsequent order). This allows us to inform PhotoSwipe of the correct index to overlay the corresponding image.

Conclusion

We have just implemented PhotoSwipe using jQuery. The code is comparably slimmer and more easily understandable than when written in vanilla JavaScript. 

Now you’re started, you can also adjust PhotoSwipe with a handful options provided and even preload the image so you will see the full image instantly upon clicking. I will leave the styles to your imagination since there are no strict rules for those.

I hope you’ve learned something from this tutorial, and find it useful at times. Don't forget to check out the live demo and leave any questions or thoughts in the comments!

Further Resources

• Getting Started with PhotoSwipe
• Responsive Images with PhotoSwipe
• 30 Days to Learn jQuery
• All You Need to Know About the HTML5 Data Attribute
• Improve Your Website's Discoverability with Semantic Markup