FAQ

Implementation

I'm unable to predefine image size, what to do?

Use another gallery script (1, 2), or find a way:

• You can read size of an image by downloading only small part of it (PHP version, Ruby, Node.js).
• You can store size of an image directly in its filename and parse it on frontend during PhotoSwipe initialization (gettingData event in API section).
• Most CMS store size of an image in a database and have API to retrieve it.
• Most web API (Facebook, 500px, Instagram, Flickr, Twitter, YouTube, Vimeo etc.) return a size of images.

Dimensions are used for progressive loading, stretched placeholder, initial zoom-in transition, panning, zooming, caption positioning. Discussion in GitHub issue #741.

My thumbnails are square, but large images have different dimensions, what to do with opening/closing transition?

1. If thumbnail aspect ratio does not match large image, do not define msrc property for slide objects and enable opacity transition option (showHideOpacity:true, getThumbBoundsFn:false).
2. If aspect ratio of thumbnail image file matches large image, but thumbnail area is cropped via CSS, just add showHideOpacity:true and make sure that getThumbBoundsFn option returns coordinates that consider crop area.

I strongly recommend to display thumbnails that match aspect ratio of large image, or crop the visible area via CSS (2).

I'll try to explain why this is not implemented yet. There are two ways to make expanding area animation:

1. Animate clip property. But it forces Paint each time, which makes animations jerky.
2. Wrap an image that expands with two divs that have overflow:hidden and reposition them via transform:translate during the animation so they clip it at right parts. This method does not force Paint or Layout, but requires two additional elements in markup of each slide. Test prototype showed that it works smooth only on high-end mobile devices (like Nexus 5 with Chrome). Maybe some day I'll implement it.

My captions are large, can I add scroll to them?

Refer to issue #657.

How to implement inline gallery display

Note that this is an experimental feature, for now it doesn't allow to scroll the page vertically over the gallery on mobile (as it calls prevetDefault() on touch events). Please report issues if you'll find any. To implement an embedded gallery that flows with the rest of your document, follow these steps:

1. Put the .pswp template inside a positioned parent element.
2. Set modal: false, closeOnScroll: false options.
3. Modify the getThumbBoundsFn (if you're using it) to subtract the template parent's bounding rect.
4. Construct the PhotoSwipe.
5. Listen for the updateScrollOffset event and add the template's bounding rect to the offset.
6. init() the PhotoSwipe.

Live example on CodePen →

<div style="position: relative;" class="parent">
    <div id="gallery" class="pswp"> ... </div>
</div>

var items = [...];
var template = document.getElementById("gallery"); // .pswp
var options = {
    ...,
    modal: false,
    closeOnScroll: false,
    getThumbBoundsFn: function(index) {
        // rect was the original bounds
        var rect = {x: ..., y: ..., w: ...},

        var templateBounds = template.parentElement.getBoundingClientRect();
        rect.x -= templateBounds.left;
        rect.y -= templateBounds.top;

        return rect;
    }
};
var photoSwipe = new PhotoSwipe(template, PhotoSwipeUI_Default, items, options);
photoSwipe.listen('updateScrollOffset', function(_offset) {
    var r = template.getBoundingClientRect();
    _offset.x += r.left;
    _offset.y += r.top;
});
photoSwipe.init();

How to use custom identifiers instead of indexes in URL

to make URLs to a single image look like this:

http://example.com/#&gid=1&pid=custom-first-id
http://example.com/#&gid=1&pid=custom-second-id

instead of:

http://example.com/#&gid=1&pid=1
http://example.com/#&gid=1&pid=2

... enable options history:true, galleryPIDs:true and add pid (unique picture identifier) property to slide objects (pid can be an integer or a string), for example:

var slides = [
    {
        src: 'path/to/1.jpg',
        w:500,
        h:400,
        pid: 'custom-first-id'
    },
    {
        src: 'path/to/2.jpg',
        w:300,
        h:700,
        pid: 'custom-second-id'
    },
    ... 
];

• Note that PhotoSwipe does not execute any code until you initialize and open it. That's why on initial page load you need to parse the URL by yourself. Default code from the Getting Started section of documentation includes this functionality (check photoswipeParseHash function if you need some modification).
• Option galleryPIDs is available since PhotoSwipe v4.0.8 (option description).

Bugs

GIF images sometimes freeze on iOS8

iOS Safari has a bug that freezes GIF images that are shifted outside of the window (or outside of element with overflow:hidden). My recommendation is to avoid using animated GIFs in PhotoSwipe at all, as they slow down animation performance in any mobile browser. But if you really need to use it, refer to this hack.

Mobile browser crashes when opening gallery with huge images

Mostly, it can happen on mobile devices with low memory limit – iOS Safari, default browser in old Android (before KitKat). The most common reason of a crash is too big images (usually larger than 2000x1500px). PhotoSwipe applies hardware-acceleration on images, which consumes more memory than regular image on page, so when you run out of limit browser starts lagging or even crashes.

So serve responsive images, or at least don't serve huge images. Ideally, for an average 900x600 phone you should serve 1200px wide image. Note that if everything works smoothly in iOS Simulator, it doesn't mean that crash won't occur on real device.

In much more rare cases crash can occur if you open PhotoSwipe during some process on your page (this can be initial page load/render, or some complex animation on page), try to delay PhotoSwipe initialization until page is rendered (18-300ms after document.ready), especially if you are displaying large images.

UPD.: in v4.1.0 this is partly fixed.

Miscellaneous

Where is the changelog, how to do I get notified about updates?

Each time PhotoSwipe gets an update - GitHub releases page is updated with details. Releases page has an Atom feed, you may setup email notifications when feed is updated using IFTTT.

Also, you may join my email newsletter (sent 3-4 times a year), follow @PhotoSwipe on Twitter, and star/watch PhotoSwipe on GitHub.

When WordPress plugin will be released?

Plugin is under development and will be released in 2015. To get notified subscribe to my newsletter.

I want to use PhotoSwipe in WordPress/Magento/Joomla... template, can I?

Yes, you can use PhotoSwipe in a free or commercial themes without any limitations. If you can, please leave a credit (link to PhotoSwipe homepage) in theme description or/and in admin area.

</> with <3 in by @dimsemenov