Beautiful Image Galleries Using PhotoSwipe

Ste Brennan
Ste Brennan

PhotoSwipe is an open source library that provides your mobile website visitors with a near “native like” gesture based image browsing experience that is not dissimilar to the image viewer app pre-bundled with iOS devices. In this article I’ll give a quick run through of getting started with PhotoSwipe as well as providing some more in-depth technical tips and tricks, which I learned along the way when developing the library.

Before we go too far, if you haven’t seen PhotoSwipe in action yet, pop along and view the PhotoSwipe Demo. We’ll be waiting for you when you return.

Getting Started

Getting started with PhotoSwipe is simple. Visit PhotoSwipe and download the latest release.

Unzipping the release you’ll find an “examples” folder which contains numerous HTML files showing you the various ways in which you can implement PhotoSwipe into your mobile website. You’ll find examples for many scenarios covering basic set up, integrating with jQuery Mobile and customising it to suit your own needs and personal tastes. Checking out these examples is without doubt the best way of getting started with PhotoSwipe.

Which Devices are Supported?

At the time of writing, PhotoSwipe works with iOS devices, Android as well as Blackberry 6 and in a limited but perfectly usable way on Windows Phone 7 Mango.

In addition, PhotoSwipe works just fine on desktop browsers. It works awesome on Firefox and, as the library is WebKit optimised, it works equally as well on Chrome and Safari. Finally, with a little help from jQuery, PhotoSwipe runs on Internet Explorer 7 and above.

Source Code, Support & Involvement

Certainly, PhotoSwipe is open sourced under the MIT license. You are free to do with it as you will!

If you would like to get involved further, or need support with an issue you may have discovered with the library, you can find Computerlove on GitHub and the PhotoSwipte Repo where you can log issues and make pull requests. You can also follow PhotoSwipe on Twitter for latest release announcements.

Getting Technical

For the rest of the article, rather than going through all the various configuration settings and ways of implementing PhotoSwipe, which are well documented on the website and demonstrated in the examples, I’ll discuss some of the principles that underpin PhotoSwipe as well as some tips and tricks that may help you when writing your own mobile website JavaScript libraries.

Letting go of jQuery, embracing jQuery

PhotoSwipe is a JavaScript library designed for mobile. Even with top end devices, there are still vast differences between desktop and mobile in terms of processing power and speed. Designing for mobile as a primary platform forced the following project constraints:

  • The library needed to be as small as possible to download. There are no guarantees that mobile website visitors are rocking on WiFi and indeed will more likely be on an intermittent 3G connection or lower.
  • The library needed be as lean as possible and only contain code and logic required for mobile browsers. Anything else would be considered as bloat and unnecessary work for a device to do.

To make things tricky, we also wanted to support desktop browsers, especially Internet Explorer, and we also wanted to ensure PhotoSwipe worked well with the rising star of mobile web libraries, jQuery Mobile.

To tackle these constraints, we followed an interface led approach. Here we agreed a core base library interface (or a defined list of core functions) that would do the underlying donkey work that PhotoSwipe needed, such as creating a DOM element, manipulating styles, adding and listening to events, animation etc.

Once we had defined this core library, we wrote an implementation of it targeting WebKit browsers and using the built in DOM standard capabilities supported by these browsers. This freed us up dramatically. We didn’t have to worry about supporting IE or other browsers that were not our primary concern. Ultimately, it meant we didn’t have to use jQuery.

Now this was a big decision! I love jQuery and it’s such a constant in popular JavaScript development, it felt odd to leave it behind. However, the decision was justified:

  • Firstly, the mobile / standards optimised version of PhotoSwipe would run on an implementation of the core library that did not include a large number of unnecessary workarounds that jQuery performs to make cross platform JavaScript as seamless as possible. Ultimately, this means less work for a mobile device to do.
  • Secondly, it saved mobile users having to download the jQuery library when, in theory, only a small percentage of it was actually needed or used by PhotoSwipe.

It was then, on top of this mobile / standards optimised implementation that the main PhotoSwipe code was developed and tested. In essence, PhotoSwipe doesn’t care how the core library is implemented. All it needs to know is that a core library supports a function that is requires such as setStyle().

At this stage, everything was good with the world. However, a key remit of the project was to support Internet Explorer and work with jQuery Mobile.

This was relatively easy to resolve. We simply developed a jQuery implementation of our core library. This meant, in a relatively short space of time and with minimal effort, we had PhotoSwipe running perfectly well on IE and running great with jQuery Mobile!

This approach also meant that should we need to, we could write core library implementations in other JavaScript libraries such as Prototype, YUI, Dojo, MooTools, Zepto and so on. This was useful in providing as much flexibility as possible for developers implementing PhotoSwipe.

Mobile Browsers are Crazy

This is something that became apparent very early on when developing PhotoSwipe. Initially, targeting WebKit seemed like an easy route. iOS, Android and BlackBerry all base their web browsers on WebKit. Optimistically, it was anticipated that this fact alone would negate a lot of potential cross platform issues.

This isn’t the case. Mobile browsers are not the same even if they are based on the same core rendering engine.

When developing mobile JavaScript components, this is something to bear in mind. The versions of WebKit are different between operating systems, as are the JavaScript interpreters used by the browsers. To compound the problems, browsers differ between versions of the same operating system. Indeed, things that worked well on earlier versions of the operating system fell apart on new versions. This was especially true on Android jumping from 1.5 to 2.1 and on iOS between the iPhone and iPad.

The main thing to remember here, is that you need a decent set of testing devices / simulators running different operating systems and different versions of operating systems. Don’t rely on the fact that they are all in essence running the same browser. With Android and Blackberry this is relatively simple as you can run multiple versions via official simulators as you need to. With iOS, it’s helpful to have a few devices lying around running different versions of iOS.

Debugging & Getting Some Help

Another issue when developing for mobile web browsers is the lack of decent debugging tools. These browsers don’t come with tools like Firebug for Firefox or the Web Inspector bundled with Chrome and Safari. Even things like getting a basic console log can be cumbersome.

In the main, this didn’t cause too much of an issue. The majority of development was in Chrome and Firefox on the desktop with continuous sanity checks on mobile devices and simulators. This meant that we could debug using Firebug and the Web Inspector.

However, sometimes bugs and quirks with the mobile browsers meant that debugging on desktop browsers was useless. You needed to know what was actually happening on the mobile device itself. For this, at least iOS comes with a developer console so you can perform some basic tracing. However this is a bit intrusive and takes up valuable screen space. Also this isn’t available on other devices such as Android.

Luckily there is help. If you haven’t already, I recommend you check out the Weinre project developed by the PhoneGap guys. This project allows you to debug what’s happening remotely on a mobile web browser, but via a debug tool running on your desktop browser!

The tool is very similar to Firebug and Web Inspector and can save you a stack of time when you hit a brick wall with something quirky going on inside a mobile web browser. Weinre is free to download, simple to setup and runs on Windows or Mac. Alternatively, there’s an online version you can use to save you having to install anything! This can be found at

Making the Most of Hardware Acceleration

One final tip is tapping into hardware acceleration on these devices, especially iOS devices. Tapping into the hardware is essential for achieving “native-like” smooth animation and interaction.

It’s pretty easy really and there are plenty of articles out there on how to achieve this. However, the basic gist is:

  • Use CSS3 transitions to achieve your animation and avoid JavaScript interval based animation when you can. You will notice a massive speed improvement by doing this.
  • The final killer tip, especially for iOS devices, is on HTML elements you are animating, if you apply “-webkit-transform: translate3d(0px, 0px, 0px);” this will trigger CSS3 animation to be hardware accelerated. It will work great in fixing any flicker you notice happening with your animations. It is worth bearing in mind however to be selective with this as over use can have a negative effect. Try your animation first without applying this to see if you really need it.

Wrapping Up

PhotoSwipe is free! Go ahead, Download PhotoSwipe, have a play and add something nice to your mobile website. If you like it, help spread the word or join us at GitHub and contribute to the future of the project.

Hopefully this article has given you some useful tips to use when developing your own mobile based JavaScript libraries, and will inspire you to write some pretty awesome mobile libraries of your own. Let us know about the awesome things you build in the comments!

Frequently Asked Questions (FAQs) about PhotoSwipe

How can I customize the PhotoSwipe gallery?

Customizing the PhotoSwipe gallery is quite straightforward. You can modify the skin CSS file to change the appearance of the gallery. The skin CSS file contains styles for the gallery controls, captions, and animations. You can also customize the gallery by modifying the options object in the JavaScript file. This object contains properties like spacing between images, loop functionality, and zoom levels. Remember to always test your changes to ensure they work as expected.

Can I use PhotoSwipe with React?

Yes, you can use PhotoSwipe with React. There are several npm packages available that integrate PhotoSwipe with React, such as ‘react-photoswipe’. You can install these packages using npm or yarn, and then import them into your React project. These packages provide React components that you can use to display your images in a PhotoSwipe gallery.

How can I add captions to my images in PhotoSwipe?

Adding captions to your images in PhotoSwipe is done by adding a ‘title’ property to the slide objects in your JavaScript file. The value of the ‘title’ property will be displayed as the caption for the image. You can include HTML in your captions, allowing you to add links, formatting, and more.

How can I use PhotoSwipe in a responsive design?

PhotoSwipe is designed to be responsive out of the box. It automatically adjusts to the size of the viewport, providing an optimal viewing experience on both small and large screens. You can further customize the responsive behavior by modifying the options object in the JavaScript file.

Can I use PhotoSwipe with WordPress?

Yes, you can use PhotoSwipe with WordPress. There are several WordPress plugins available that integrate PhotoSwipe into your WordPress site, such as ‘WP PhotoSwipe’. These plugins allow you to easily add PhotoSwipe galleries to your posts and pages.

How can I add thumbnails to my PhotoSwipe gallery?

Adding thumbnails to your PhotoSwipe gallery requires modifying the HTML markup for your gallery. You need to add ‘img’ elements for your thumbnails inside the ‘figure’ elements for your slides. The ‘src’ attribute of the ‘img’ elements should point to the thumbnail images.

How can I add a download button to my PhotoSwipe gallery?

Adding a download button to your PhotoSwipe gallery requires modifying the skin CSS file and the JavaScript file. In the skin CSS file, you need to add styles for the download button. In the JavaScript file, you need to add an event listener for the download button that triggers the download of the current image.

Can I use PhotoSwipe with Angular?

Yes, you can use PhotoSwipe with Angular. There are several npm packages available that integrate PhotoSwipe with Angular, such as ‘ngx-photoswipe’. You can install these packages using npm or yarn, and then import them into your Angular project. These packages provide Angular components that you can use to display your images in a PhotoSwipe gallery.

How can I add a fullscreen button to my PhotoSwipe gallery?

Adding a fullscreen button to your PhotoSwipe gallery requires modifying the skin CSS file and the JavaScript file. In the skin CSS file, you need to add styles for the fullscreen button. In the JavaScript file, you need to add an event listener for the fullscreen button that toggles the fullscreen mode.

How can I add a zoom button to my PhotoSwipe gallery?

Adding a zoom button to your PhotoSwipe gallery requires modifying the skin CSS file and the JavaScript file. In the skin CSS file, you need to add styles for the zoom button. In the JavaScript file, you need to add an event listener for the zoom button that toggles the zoom level.