Getting Started
Before you start:
- PhotoSwipe requires predefined image dimensions, you must define width and height of each image.
- PhotoSwipe is not designed to display very large images. Serve responsive images. Maximum recommended size is 3000x3000px. However, there is an experimental tiling plugin that allows to show extremely large images.
- PhotoSwipe works only in modern browsers. The script is distributed as ES6 module, thus it will work only in browsers that support them (caniuse). You can transpile it to ES5, but it's redundant.
Initialization
The PhotoSwipe consists of three parts:
- Core (
photoswipe.esm.js
). - Lightbox (
photoswipe-lightbox.esm.js
) - loads Core and chooses when PhotoSwipe should be opened. Its file size is significantly smaller. It also loads the first image (in parallel with Core). - CSS (
photoswipe.css
) - a single file that controls all the styling. There are no external assets for icons - all of them are dynamically generated via JS and very tiny. Refer to styling for more info.
JS files are separated, so you can dynamically load Core only when user actually needs it, thus reducing the size of your main bundle.
If you aren't using any bundlers of frameworks, you may use a single <script type="module"></script>
to add inline JS code to your page, for example:
<script type="module">
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
gallery: '#my-gallery',
children: 'a',
pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.init();
</script>
If you're using package manager:
npm install --save photoswipe#beta
Basic vanilla JS example
// Include Lightbox
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
// may select multiple "galleries"
gallery: '#gallery--getting-started',
// Elements within gallery (slides)
children: 'a',
// setup PhotoSwipe Core dynamic import
pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.init();
<div class="pswp-gallery pswp-gallery--single-column" id="gallery--getting-started">
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg"
data-pswp-width="1669"
data-pswp-height="2500"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg" alt="" />
</a>
<!-- cropped thumbnail: -->
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-2500.jpg"
data-pswp-width="1875"
data-pswp-height="2500"
data-cropped="true"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-200.jpg" alt="" />
Cropped
</a>
<!-- data-pswp-src with custom URL in href -->
<a href="https://unsplash.com"
data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
data-pswp-width="2500"
data-pswp-height="1666"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
</a>
<!-- Without thumbnail: -->
<a href="http://example.com"
data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/5/img-2500.jpg"
data-pswp-width="2500"
data-pswp-height="1668"
target="_blank">
No thumbnail
</a>
<!-- wrapped with any element: -->
<div>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/6/img-2500.jpg"
data-pswp-width="2500"
data-pswp-height="1667"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/6/img-200.jpg" alt="" />
</a>
</div>
</div>
Without dynamic import
You don't have to dynamically import pswpModule, especially if PhotoSwipe is one of the primary features of your page.
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
import PhotoSwipe from '/photoswipe/photoswipe.esm.js';
const lightbox = new PhotoSwipeLightbox({
gallery: '#gallery--no-dynamic-import',
children: 'a',
pswpModule: PhotoSwipe
});
lightbox.init();
<div class="pswp-gallery" id="gallery--no-dynamic-import">
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-2500.jpg"
data-pswp-width="1875"
data-pswp-height="2500"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-200.jpg" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg"
data-pswp-width="1669"
data-pswp-height="2500"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
data-pswp-width="2500"
data-pswp-height="1666"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
</a>
</div>
Required HTML markup
Each element that matches the selector should be or should contain link <a>
element. The link must have such attributes:
- Image URL in
href
ordata-pswp-src
attribute (latter has higher priority). - Image width in
data-pswp-width
. - Image height in
data-pswp-height
.
And optionally:
<img>
thumbnail within the link element that will be displayed before large image is loaded (applied only for the first image, can be adjusted viathumbSelector
).- Optional
data-cropped="true"
attribute if thumbnail is cropped.
PhotoSwipe API supports almost any markup and any datasource, read more about it here.
Open each image individually
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const options = {
gallery: '#gallery--individual a',
pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.init();
<div class="pswp-gallery" id="gallery--individual">
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-2500.jpg"
data-pswp-width="1875"
data-pswp-height="2500"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-200.jpg" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg"
data-pswp-width="1669"
data-pswp-height="2500"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
data-pswp-width="2500"
data-pswp-height="1666"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
</a>
</div>
Responsive images with srcset
- Add
data-pswp-srcset
attribute. It supports the same markup as native srcset. - Attributes
data-pswp-width
anddata-pswp-height
should define the largest image size. sizes
attribute will be generated automatically based on actual width of the image. For example, if user zooms-in -sizes
will be adjusted to the new zoom level.
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const options = {
gallery: '#gallery--responsive-images',
children: 'a',
pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.init();
<div class="pswp-gallery" id="gallery--responsive-images">
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/1-1500x1000.png"
data-pswp-width="1500"
data-pswp-height="1000"
data-pswp-srcset="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/1-600x400.png 600w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/1-1200x800.png 1200w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/1-1500x1000.png 1500w"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/1-300x200.png" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/2-1500x1000.png"
data-pswp-width="1500"
data-pswp-height="1000"
data-pswp-srcset="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/2-600x400.png 600w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/2-1200x800.png 1200w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/2-1500x1000.png 1500w"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/2-300x200.png" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/3-1500x1500.png"
data-pswp-width="1500"
data-pswp-height="1500"
data-pswp-srcset="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/3-600x600.png 600w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/3-1200x1200.png 1200w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/3-1500x1500.png 1500w"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/3-300x300.png" alt="" />
</a>
<a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/4-1000x1500.png"
data-pswp-width="1000"
data-pswp-height="1500"
data-pswp-srcset="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/4-400x600.png 400w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/4-800x1200.png 800w, https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/4-1000x1500.png 1000w"
target="_blank">
<img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/srcset-test/4-200x300.png" alt="" />
</a>
</div>
Supported browsers and fallback
- The PhotoSwipe supports all browsers that support ES6 modules.
- Thus, it might not work in IE11, Opera Mini, UC browser, and old versions of Chrome, Safari and Firefox. Check your website/region statistics before deciding whether you should use PhotoSwipe or not.
- Users in unsupported browsers will still be able to view the large image if you use recommended HTML markup - link to image, or link to pa age that contains image.
- You may add any fallback via
script type="nomodule"
.