Options

bgOpacity

Number, 0.8.

Background backdrop opacity, always define it via this option and not via CSS rgba color.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-bgopacity',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  bgOpacity: 0.2,
});
lightbox.init();

spacing

Number, 0.1. Spacing between slides. Defined as ratio relative to the viewport width (0.1 = 10% of viewport).

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-spacing',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  spacing: 0.5, // 50% of viewport width
});
lightbox.init();

allowPanToNext

Boolean, true. Allow swipe navigation to the next slide when the current slide is zoomed. Does not apply to mouse events.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-spacing',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  allowPanToNext: false
});
lightbox.init();

loop

Boolean, true. If set to true you'll be able to swipe from the last to the first image. Option is always false when there are less than 3 slides.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-loop',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  loop: false
});
lightbox.init();

wheelToZoom

Boolean, undefined. By default PhotoSwipe zooms image with ctrl-wheel, if you enable this option - image will zoom just via wheel.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-wheelToZoom',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  wheelToZoom: true
});
lightbox.init();

pinchToClose

Boolean, true. Pinch touch gesture to close the gallery.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-pinch-to-close',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  pinchToClose: false
});
lightbox.init();

closeOnVerticalDrag

Boolean, true. Vertical drag gesture to close the PhotoSwipe.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--close-on-vertical-drag',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  closeOnVerticalDrag: false
});
lightbox.init();

padding

Object, { top: 0, bottom: 0, left: 0, right: 0 }. Slide area padding (in pixels).

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-padding',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  padding: { top: 20, bottom: 40, left: 100, right: 100 }
});
lightbox.init();

paddingFn

Function, should return padding object. The option is checked frequently, so make sure it's performant. Overrides padding option if defined. For example:

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-paddingfn',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),

  paddingFn: (viewportSize, itemData, index) => {
    return {
      // check based on slide index
      top: index === 0 ? 100 : 0,

      // check based on viewport size
      bottom: viewportSize.x < 600 ? 0 : 200,

      // check based on image size
      left: itemData.w < 2000 ? 50 : 0,

      right: 0
    };
  }
});
lightbox.init();

hideAnimationDuration, showAnimationDuration, zoomAnimationDuration

Number, 333. Transition duration in milliseconds, can be 0. Example here.

easing

String, 'cubic-bezier(.4,0,.22,1)'. CSS easing function for open/close/zoom transitions. Example here.

escKey

Boolean, true. Esc key to close.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-esc-key',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  escKey: false
});
lightbox.init();

arrowKeys

Boolean, true. Left/right arrow keys for navigation.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-arrow-keys',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  arrowKeys: false
});
lightbox.init();

trapFocus

Boolean, true. Trap focus within PhotoSwipe element while it's open.

returnFocus

Boolean, true. Restore focus the last active element after PhotoSwipe is closed.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-restore-focus',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  returnFocus: false
});
lightbox.init();

clickToCloseNonZoomable

Boolean, true. If image is not zoomable (for example, smaller than viewport) it can be closed by clicking on it.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--clickToCloseNonZoomable',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  clickToCloseNonZoomable: false
});
lightbox.init();

imageClickAction, bgClickAction, tapAction, doubleTapAction

Refer to click and tap actions page.

preloaderDelay

Number (ms), 2000. Delay before the loading indicator will be displayed, if image is loaded during it - the indicator will not be displayed at all. Can be zero.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-preloader-delay',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preloaderDelay: 0
});
lightbox.init();

indexIndicatorSep

String, /. Used for slide count indicator ("1 of 10 ").

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-indexIndicatorSep',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  indexIndicatorSep: ' of '
});
lightbox.init();

getViewportSizeFn

Function {x: width, y: height}, undefined. A function that should return slide viewport width and height, in format {x: 100, y: 100}.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-getViewportSizeFn',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  getViewportSizeFn: function(options, pswp) {
    return {
      x: document.documentElement.clientWidth - 200,
      y: window.innerHeight
    };
  }
});
lightbox.init();

initialZoomLevel, secondaryZoomLevel, maxZoomLevel

Refer to Adjusting zoom level page for more info. The default values are described there too.

errorMsg

String, 'The image cannot be loaded'.

Message to display when the image wasn't able to load. If you need to display HTML - use contentErrorElement filter.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--errorMsg',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  errorMsg: 'The photo cannot be loaded'
});
lightbox.init();

preload

Array, [1, 2]. Lazy loading of nearby slides based on direction of movement. Should be an array with two integers, first one - number of items to preload before the current image, second one - after the current image. Two nearby images are always loaded.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-preload',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preload: [1, 4]
});
lightbox.init();

mainClass

String, undefined. Class that will be added to the root element of PhotoSwipe, may contain multiple separated by space. Example on Styling page.

appendToEl

DOMElement, document.body. Element to which PhotoSwipe dialog will be appended when it opens.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-appendToEl',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  appendToEl: document.querySelector('#__docusaurus')
});
lightbox.init();

maxWidthToAnimate

Integer, 4000. Maximum width of image to animate, if initial rendered image width is larger than this value - the opening/closing transition will be automatically disabled.

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-maxWidthToAnimate',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  maxWidthToAnimate: 800,
});
lightbox.init();

Lightbox module options

See getting started and data sources for examples.

gallery

Element, NodeList, or CSS selector (string) for the gallery element.

children

Element, NodeList, or CSS selector (string) for elements within gallery. For example, link elements. If not defined or set to false - root gallery node will be used.

pswpModule

Function or Module, undefined. A function that should return import() promise (if you need dynamic import), for example:

pswpModule: () => import('photoswipe/dist/photoswipe.esm.js');

Or the PhotoSwipe Core module itself, for example:

import PhotoSwipeLightbox from 'photoswipe/dist/photoswipe-lightbox.esm.js';
import PhotoSwipe from 'photoswipe/dist/photoswipe.esm.js';

const lightbox = new PhotoSwipeLightbox({
  pswpModule: PhotoSwipe
  // ...
});

preloadFirstSlide

Boolean, true. Loads the first slide image in parallel with PhotoSwipe Core (while PhotoSwipe is opening).

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-appendToEl',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preloadFirstSlide: false
});
lightbox.init();

Translating

A list of options that might need a translation:

closeTitle: 'Close',
zoomTitle: 'Zoom',
arrowPrevTitle: 'Previous',
arrowNextTitle: 'Next',

errorMsg: 'The image cannot be loaded',
indexIndicatorSep: ' / ',

Example:

import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-i18n',
  children: 'a',

  closeTitle: 'Close the dialog',
  zoomTitle: 'Zoom the photo',
  arrowPrevTitle: 'Go to the previous photo',
  arrowNextTitle: 'Go to the next photo',

  errorMsg: 'The photo cannot be loaded',
  indexIndicatorSep: ' of ',

  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preloadFirstSlide: false
});
lightbox.init();