JavaScript image gallery for mobile and desktop, modular, framework independent


Stand With Ukraine

PhotoSwipe v5 — JavaScript image gallery and lightbox

Demo | Documentation

Sponsor via OpenCollective Follow on Twitter

Repo structure

  • dist/ - main JS and CSS
  • src/ - source JS and CSS.
    • src/js/photoswipe.js - entry for PhotoSwipe Core.
    • src/js/lightbox/lightbox.js - entry for PhotoSwipe Lightbox.
  • docs/ - documentation markdown files.
  • demo-docs-website/ - website with documentation, demos and manual tests.
  • build/ - rollup build config.

To build JS and CSS in dist/ directory, run npm run build.

To run the demo website and automatically rebuild files during development, run npm install in demo-docs-website/ and npm run watch in the root directory.

Older versions

Documentation for the old version (v4) can be found here and the code for 4.1.3 is here.

  • Video support

    Video support

    Now that is v4.0, have you got any plan on introducing it? I remember that old versions was not doing it. I was hoping that now that you're managing it maybe it could be introduced. See for an example.

    Thanks in advance :)

    P.S.: if you need some inputs or user-cases feel free to ask them, since I've already patched swipebox to support a better embedding of video URLs :)

    Feature Request 
    opened by julianxhokaxhiu 46
  • Responsive Example ?

    Responsive Example ?

    Using the JS from this CodePen and am trying to add responsive images as functionality to it but I do not know how to do that.

    Can I simply replace:

                // create slide object
                item = {
                    src: linkEl.getAttribute('href'),
                    w: parseInt(size[0], 10),
                    h: parseInt(size[1], 10)


    var items = [
        // Slide 1
            mediumImage: {
                src: 'path/to/medium-image-1.jpg',
            originalImage: {
                src: 'path/to/large-image-1.jpg',
                w: 1400,
                h: 1050
        // Slide 2
        // {
        //     mediumImage: {
        //         src: 'path/to/medium-image-2.jpg',
        //         ...
        // ...

    and then add

    // create variable that will store real size of viewport
    var realViewportWidth,
        useLargeImages = false,
        firstResize = true,
    // beforeResize event fires each time size of gallery viewport updates
    gallery.listen('beforeResize', function() {
        // gallery.viewportSize.x - width of PhotoSwipe viewport
        // gallery.viewportSize.y - height of PhotoSwipe viewport
        // window.devicePixelRatio - ratio between physical pixels and device independent pixels (Number)
        //                          1 (regular display), 2 (@2x, retina) ...
        // calculate real pixels when size changes
        realViewportWidth = gallery.viewportSize.x * window.devicePixelRatio;
        // Code below is needed if you want image to switch dynamically on window.resize
        // Find out if current images need to be changed
        if(useLargeImages && realViewportWidth < 1000) {
            useLargeImages = false;
            imageSrcWillChange = true;
        } else if(!useLargeImages && realViewportWidth >= 1000) {
            useLargeImages = true;
            imageSrcWillChange = true;
        // Invalidate items only when source is changed and when it's not the first update
        if(imageSrcWillChange && !firstResize) {
            // invalidateCurrItems sets a flag on slides that are in DOM,
            // which will force update of content (image) on window.resize.
        if(firstResize) {
            firstResize = false;
        imageSrcWillChange = false;
    // gettingData event fires each time PhotoSwipe retrieves image source & size
    gallery.listen('gettingData', function(index, item) {
        // Set image source & size based on real viewport width
        if( useLargeImages ) {
            item.src = item.originalImage.src;
            item.w = item.originalImage.w;
            item.h = item.originalImage.h;
        } else {
            item.src = item.mediumImage.src;
            item.w = item.mediumImage.w;
            item.h = item.mediumImage.h;
        // It doesn't really matter what will you do here, 
        // as long as item.src, item.w and item.h have valid values.
        // Just avoid http requests in this listener, as it fires quite often
    // Note that init() method is called after gettingData event is bound

    in between

            // Pass data to PhotoSwipe and initialize it
            gallery = new PhotoSwipe( pswpElement, PhotoSwipeUI_Default, items, options);
            // insert responsive image code here 


    I have looked at the index.html from the website folder of this repo and loaded it on the local server with XAMPP but it does not work at all, meaning PhotoSwipe is not initialized. I thought that the website folder is a fully working example, as repsonsive image code is found in the JS section of that index.html file.

    Does any one have a working example of how to get responsive images working with PhotoSwipe on a server that does have medium and large images? Or is there a live website perhaps that uses responsive images with PhotoSwipe?

    I am really new to JS and trying to put the pieces together. My question is basically how can I get the JS to read the var items = .. for responsive images when using the JS from this CodePen ?

    Since the slide object is parsed with JS from the DOM I have no clue where to add the responsive images object in the JS.

    Any help or live example would be awesome.

    opened by ghost 30
  • 3rd Image always stuck on loading image

    3rd Image always stuck on loading image


    Pretty sweet plugin. Trying to use the exclusive mode with no thumbnails. I'm also using jQuery mobile. It seems no matter what I do, photoswipe always shows a loading indicator for the 3rd image, and it never loads. Your exclusive mode doesn't have an example using jQuery mobile, but I get the idea. I just put the var options in the jQuery document ready. However, even if I use the non-jQuery call, the same exact thing happens. Any ideas?

    Thanks, -Jon

    opened by wjthomas9 29
  • Basic modal functionality

    Basic modal functionality

    Hey dimsemenov,

    I saw there was basic work being done on a modal/non-modal option. I'm interested in having a photoswipe gallery embedded in as part of the page rather than taking up the entire space so I went ahead and made the modal option do this. Let me know if this works, and if there's anything else to add!

    To use in a non-modal situation, place the template inside a positioned element and the photoswipe gallery will take up the space of the parent when opened.

    Currently known bug: two-finger zoom offsets the image as if it were based off the entire screen rather than just the parent. I couldn't find where those calculations happened exactly, so the bug exists in this current state. If you could direct me to how the calculation is done I'll fix the bug. Thanks!

    opened by hellochar 27
  • zooming not working in android

    zooming not working in android

    Thank you for PhotoSwipe. I am using jquery-1.6.4.min.js,code.photoswipe.jquery-3.0.5.min.js, , there is no error except zooming in android. Pinch and zoom works in ipad,iphone why its not working in android. solutions please.........

    Feature Request Old PhotoSwipe 
    opened by rambo123 27
  • [iOS] Load a large images

    [iOS] Load a large images

    When you have a large images in your gallery, for example: 200 images, each image about 70K, so the total load is: 200x70=14,000k = 14 MB

    Yeah .... but look at this link:,

    And we can see some first images in the gallery, in this case I can see first 140 images (140x70 = 9800KB), and other images (141, 142, .... 200) I can't see it ? is this a bug ?

    Thanks for a cool framework ......

    opened by phuocle 26
  • Added object-position property support.

    Added object-position property support.

    I was trying to add a basic object-position support.

    This approach ~~requires to use additional data attribute data-cropped-position~~:

    <a ...
      <img ../>
    img {
      object-fit: cover;
      object-position: center top;

    Demo link:

    Needs review 
    opened by vovayatsyuk 24
  • Can't share images via photoswipe-ui-default.js default setup, nor any I've tried

    Can't share images via photoswipe-ui-default.js default setup, nor any I've tried

    Having a heckuva time trying to share images from PhotoSwipe in social media. Neither Facebook nor Pinterest shares are working, they both give image url errors. I've tried various things, culled from issue posts here and elsewhere, but can't get anything to work. I know Facebook has changed things. Does anyone have a setup that works?

    I'm using the app_id in the Facebook share line, which I believe you need now. The line I'm using now in photoswipe-ui-default.js is: {id:'facebook', label:'Share on Facebook', url:'{{url}}&picture={{raw_image_url}}'}, ... with my proper add_id in there, of course. I've also tried image_url instead of raw_image_url, but same result. The Facebook error says: "picture should represent a valid URL". However, the same raw_image_url used in the {id:'download', label:'Download image', url:'{{raw_image_url}}', download:true} line works fine, and returns a valid url, so I don't know why FB can't extract a good url.

    When attempting to share via Pinterest, I also get an image url error message, saying: "Parameter 'image_url' (value https:../cartoons/01.jpg) is not a valid URL format", using that abbreviated url in the message. I'm not sure if that's the actual url Pinterest is getting, thus causing the error, or if their error message just shortens it. Again, I can't see why the url would be bad, since it works with the Download image link.

    Any help would be much appreciated. Thank you.

    opened by jamminjames 23
  • Feature request/suggestion

    Feature request/suggestion

    Safari on iPad has the feature that if you tap and hold an image you can save it. This seems to work only if you do that to an img element (though I haven't thoroughly checked that). In the photoswipe image gallery this doesn't work as you are hovering over something else apparently. Would it be possible to modify photoswipe accordingly? Would be really cool if you could save images that way.

    opened by Hk1020 23
  • jquery-1.7.1.min.js Bug

    jquery-1.7.1.min.js Bug

    Thank you for PhotoSwipe.

    Pinch and zoom on an image loaded in a gallery, using the jquery example and my own web app, breaks when using jquery-1.7.1.min.js. With no other changes jquery-1.6.4.min.js works beautifully. By breaks I mean the screen goes black, everything disappears and requires a reload of the page to return.

    opened by moonerent 21
  • Uncaught TypeError: Cannot read property 'x' of undefined

    Uncaught TypeError: Cannot read property 'x' of undefined

    I've already solved the problem, adding here to document the problem, in case someone runs into this as I did

    Uncaught TypeError: Cannot read property 'x' of undefined error threw me off for a good 2 hours.

    I read almost every line of the Call Stack in chrome debugger, ( it lead _equalizePoints() ), going back and forth until I discovered, that I had specified the images object like this:

    image.push({ src: "http://----.jpg", width: 100, height 100 });

    As it turns out, the expected keys for width & height are w and h, and not width or height.

    I assume that because PhotoSwipe is still in beta, there is no throwing of error helpful error messages, when data is missing. A "No width or height of image found" would have been very helpful, instead I tried to inspect the bounds of my images, try to figure out when and what is called, etc.

    opened by pyronaur 20
  • Nuxt 3 compatibility

    Nuxt 3 compatibility

    Hello, I am trying to to use photoswipe in my Nuxt 3 app. For now I can't make it work:

    • I have an error when importing photoswipe in a