PhotoSwipe v4.1.1

JavaScript gallery, no dependencies.

This is dummy caption.

This is dummy caption. It has been placed here solely to demonstrate the look and feel of finished, typeset text.

This is dummy caption. It is not meant to be read.

Dummy caption. It's Greek to you. Unless, of course, you're Greek, in which case, it really makes no sense.

It's a dummy caption. He who searches for meaning here will be sorely disappointed.

Demo gallery style

All controls
caption, share and fullscreen buttons, tap to toggle controls

Minimal
no caption, transparent background, tap to close

Touch gestures

All basic gestures are supported: flick to the next or previous image, spread to zoom in, drag to pan, pinch to zoom out or close, tap to toggle the controls, double-tap to zoom.*

Spread to zoom image

PhotoSwipe is the first open-source gallery to support JavaScript-based image zooming. Even if a browser’s native zooming has been disabled, image zooming will still work.

Pinch to close gallery

The gallery’s background will gradually fade out as the user zooms out. When the gesture is complete, the gallery will close.

Vertical swipe to close gallery

Gesture is added because close button in top right corner might be hard to reach on tall mobile devices while holding in one hand.

Horizontal swipe to switch items

Images can be changed even when current slide is zoomed. Swiping is not blocked during the transition.

*You can assign your own actions for tap and double-tap gestures.

Browser history API

PhotoSwipe manipulates the browser’s history so that the user can link to each gallery item and close the gallery via the “back” button. The initial URL is restored when the gallery is closed.

“Back” button to close gallery

PhotoSwipe adds a history record when the gallery is opened, which allows the user to close it via the browser’s “back” button.

Unique URL for each gallery item

Users can share and link to each image. The hash suffix gets two extra parameters: gid (the gallery index) and pid (the picture index).

This feature comes as a module. You can exclude it from the build entirely, or fork it to fit the requirements of your product’s URL structure.

Loading and displaying images

PhotoSwipe creates the illusion of faster loading.

Images display progressively as data arrives

Photos are displayed before they fully load. This feature is disabled on touch devices because it could cause swipe transitions to lag.

Low-resolution images are instantly displayed and then stretched to full size

Pass the source of a thumbnail to PhotoSwipe, which will display it instantly and load the full-sized image over top.

Smart loading indicator

Just a stretched thumbnail or gray placeholder is used, with the full image progressively loaded over top.

Luke Wroblewski on spinners:
“It’s like watching the clock tick down—when you do, time seems to go slower.”

If at least a tiny part of the image has not loaded for 1 second or a browser does not support progressive loading, a spinning progress indicator smoothly fades in. A delay is added to avoid blinking in case the image was cached or the user has a fast connection.

Zoom animation

The zoom transition to open the gallery wasn’t added merely for a fancy effect. The image starts loading before the animation, so users on fast connections might not even notice that something was loading.

Smart lazy-loading

PhotoSwipe loads neighboring images based on the direction of the user’s movement. You can control how many images to preload through the API.

Responsive images support

Because images in a gallery are loaded dynamically, you can pass the source that is appropriate to the user’s window size and DPI.
More about responsive images →

Semantic and SEO friendly markup

PhotoSwipe allows to define absolutely any HTML text for gallery. You can use Schema.org structured data markup for ImageGallery.
More about search-optimized gallery →

Zoom on the desktop, too

PhotoSwipe emulates the default behavior of the browser’s image viewer.

Click to zoom image

If an image is smaller than the viewport, PhotoSwipe will show a zoom cursor over the image and zoom icon in the top bar.

Pan via the wheel or trackpad or by dragging

When an image is zoomed in, the user can pan across it via the mouse wheel or the trackpad or by dragging it. And if you need to extend this functionality, you can use the API, of course.

User interface

The UI is entirely separated from the core of the script. If you’re making a custom interface for a gallery, you would write it instead of the default interface, not on top of it. Default PhotoSwipe UI is responsive – optimized for desktop, tablets and mobile devices.

Pixel-perfect vector icons

SVG sprites are used for high-DPI screens, like Retina displays. PNG is used for regular (@1x) displays.

Social sharing

The default UI has a button that pops open a window with sharing links. The default links are for Facebook, Twitter and Pinterest, but you can, of course, add more via the API.

Native HTML5 full-screen

A full-screen image-viewing experience is supported, including on mobile devices with native full-screen support.

Keyboard access

Galleries can be navigated via the arrow keys and closed via the “Escape” key. The controls (including the sharing buttons) can be focused on with the “Tab” button.

Also

To draw the most attention to the photos, controls are hidden when the mouse hasn’t moved for 2 seconds or when the mouse moves off the window.

PhotoSwipe can be closed simply by scrolling the page (on non-touch devices), thus avoiding any extra movement of the mouse.

The background can be set to any color and transparency level.

The vertical margins between images can be controlled through an API.

PhotoSwipe is treated as a modal dialog, so aria attributes are added, and the gallery gains focus when it is open.

Problems solved by PhotoSwipe

Images are displayed at their highest possible size and are not limited by the width of the column or wrapper. Each image is isolated from the other content and fits the viewport vertically, so that the user can focus on it. If an image is larger than the viewport, it can be zoomed (which most galleries are unable to do).

Detail is preserved in responsive images

Let’s say the viewport on a user’s phone is 500 pixels wide and your uncompressed image is 1200 pixels wide. You wouldn’t want to serve such a large image on mobile, so perhaps you’d resize it to 500 pixels. But if the image has important details and the user zooms it, it will look pixelated. With PhotoSwipe, when the user taps the small image (500 pixels), the large one will load (1200 pixels), thus preserving all of the detail.

Compared to an inline horizontal JavaScript gallery

PhotoSwipe will not slow the page from loading, because you can defer loading the gallery’s JavaScript file or even load it after the user has clicked the “Open gallery” button.

Compared to a list of images, one after another

PhotoSwipe saves users’ bandwidth because it doesn’t load all images at once — just nearby images according to the user’s direction of movement. Also, it occupies less space on the page, and you can directly link to individual images in a gallery.

PhotoSwipe might not be a good idea if…

… your images are small or low quality or if there would be no point in zooming or isolating them. Use a simple list of images or a horizontal scroller instead.
… your images are very large and should never be scaled (for example tall infographics with text). Simply link to image file, or create separate HTML page just with image.
… your captions are long or more important than the images themselves. Consider using a simple list of images, with captions below or beside them. And when the user clicks on an image for which a larger version is available, then you could open PhotoSwipe, without the caption, to draw attention to the image itself.
… your website’s layout is not fluid. On a non-responsive website on a small screen, PhotoSwipe’s controls would look tiny because the page will be zoomed out. Consider using Magnific Popup instead.

Technical specifications

PhotoSwipe is built for performance and integration with your product needs.

Modules and size breakdown

PhotoSwipe is broken down into modules. All of them, except the controller, events & gestures and framework bridge, may be excluded from your build to reduce the size. You’re free to edit any of these to fit your requirements. Built with Grunt, linted with JSHint.

3.6 KB

3.2

2.6

1.9

Core
basic functionality, like switching items or zooming
User interface
all buttons and their actions, captions, etc. (the interface is built exclusively with public methods — an example of what the API can do)
Events & gestures
touch, pointer, mouse events and gestures
Controller
managing gallery items; adding content to the gallery; returning the sizes of images

Framework bridge
generic functions, like addClass and addEventListener; feature detection
History
changes URL’s hash suffix (#); enables browser’s “back” button to close gallery
Desktop zoom
clicking to zoom; panning with trackpad or mouse wheel.
Tap
firing tap and double-tap events

The total size of core modules (Gzip’d) is about 11 KB + 3 KB UI, which is about three times lighter than jQuery 1.11 and only 2 KB heavier than FancyBox.
The CSS comes out to 0.5 KB core + 1.5 KB skin + single SVG or PNG icons sprite. Uses Sass preprocessor.

Animation

RequestAnimationFrame is used wherever possible.
Only the transform and opacity properties are animated. Almost no paints occur during animation, making transitions as smooth as possible.
The frames-per-second (FPS) rate largely depends on the sizes of the images and the device itself. For example, landscape-oriented images that are 1000 pixels wide and displayed in portrait mode on an iPhone 4s running iOS 8 will animate smoothly at 60 FPS. If the images were 1400 pixels wide, then the FPS rate would drop noticeably.

Memory

PhotoSwipe keeps only three images in the DOM at once, because each “slide” is a composited layer, which consumes quite a lot of memory.
Almost no memory is consumed until the gallery is first opened.
The script has been tested for memory leaks. Navigating images back and forth and creating or deleting a gallery doesn’t leave a trace in memory.

Supported browsers and devices

The script has been developed to work on every device, which means that basic functionality should be supported everywhere:

desktop Chrome, Firefox, Safari, Opera and IE 8 and above
Android 2.3.7+ (2.1 not tested yet): default browser, Chrome, Firefox (latest), Dolphin (latest)
iOS 5+
Windows Phone 7+: default browser (touch gestures are supported from 8+)
BlackBerry OS 10+: default browser (older versions not tested yet)
devices with multiple input methods (Surface, Chromebook Pixel, etc.)

If you discover a problem on your device, please open an issue on GitHub, and provide as much detail as possible (OS name and version, browser name and version, screenshot or screencast, etc.).

How PhotoSwipe determines whether a mouse is being used

If both touch and mouse input methods are detected, the script waits for two consecutive mousemove events to occur and only then applies the mouse-only features (for example left/right arrow buttons).

How the zoom animation works for opening images

Once a thumbnail is clicked, its large version instantly starts loading.
Meanwhile, PhotoSwipe creates a fixed-positioned layer with the duplicated thumbnail image, background, buttons and caption. The background and controls are styled with opacity: 0.001 (if it had opacity: 0, the paint would not occur in some browsers).
A 50-millisecond timer starts. It is added to give the browser time to render the new layers (background, controls, image). Otherwise, the animation would start with a noticeable lag. TODO: change this delay depending on browser/os/device?
Three CSS transitions start: one scales the image (scale and translate are animated), the second changes the opacity of the background, and the third changes the opacity of the controls.
By default, the transition lasts 333 milliseconds.
The background is a separate element, because animating opacity looks much smoother than animating an RGBa background-color.
Once the transition is complete, the large image is added on top of the stretched thumbnail, whether or not it’s fully loaded.
To make the swipe transition smooth, the two neighboring slides are readied at the sides of the viewport.
If lazy-loading is enabled on more than two neighboring images, then those images would start to load now, too.

Are PhotoSwipe images crawlable by search engines?

PhotoSwipe does not force any HTML markup into the gallery — you have full control. Images will be crawlable if you'll have list of links to large images or the images themselves.

License and price

The script is free to use for personal and commercial projects. It falls under the MIT license with one exception: Do not create a public WordPress plugin based on it, as I will develop it.
If you need to use it for a public WordPress plugin right now, please ask me by email first. Thanks!

Attribution is not required, but much appreciated, especially if you're making product for developers.

About

The script was created by Code Computerlove, a digital agency in Manchester. In March 2014, it passed on development to Dmitry Semenov.
The new version of PhotoSwipe (4.0) was entirely rewritten, supports a much longer list of devices, and contains a lot of performance and UX improvements. Built-in support for jQuery Mobile has been dropped.