PhotoSwipe

You can modify the slides in a running PhotoSwipe instance by manipulating pswp.options.dataSource.

• If initialized from DOM elements, dataSource contains a gallery element and an items array of child elements.
• If initialized from an array, dataSource is the array itself.

Crucial Step: If you modify a slide that is currently active (the current, next, or previous slide), you MUST call pswp.refreshSlideContent(slideIndex) to reload that specific slide with the new data.

// Example: Replacing the current slide's data
pswp.options.dataSource[pswp.currSlide.index] = {
  src: 'new-image.jpg', 
  width: 800, 
  height: 600
};
pswp.refreshSlideContent(pswp.currSlide.index);

// Example: Adding a new slide to the end
pswp.options.dataSource.push({
  src: 'added-image.jpg', 
  width: 800, 
  height: 600
});
pswp.refreshSlideContent(pswp.getNumItems() - 1);

If not explicitly configured, PhotoSwipe uses the following default zoom levels:

• Initial zoom level: 'fit'
• Secondary zoom level: 2.5x of 'fit', but capped at a maximum width of 3000px.
• Maximum zoom level: 4x of 'fit'.

By default, PhotoSwipe supports image and html content types. To support new types (like WebP <picture> elements or <iframe> embeds), you must use the addFilter method to extract custom data and event listeners to override the default rendering behavior.

Key lifecycle events for custom content:

• contentLoad: Use this to define the content element (e.g., creating a <div> or <picture> instead of the default <img>). Call e.preventDefault() to stop PhotoSwipe from using its default logic.
• contentAppend: Use this to manually append your custom element to the slide container.
• contentRemove: Use this to clean up your custom elements when navigating away from a slide.

Note: PhotoSwipe is optimized for photos. Interactive content like iframes may have issues with swiping gestures. Always provide an outbound link as a fallback.

To work with PhotoSwipe, your HTML elements (usually <a> tags) must include specific data attributes.

Required Attributes

• href or data-pswp-src: The URL of the large image. data-pswp-src has higher priority.
• data-pswp-width: The width of the image.
• data-pswp-height: The height of the image.

Optional Attributes

• data-pswp-srcset: Supports native srcset markup for responsive images.
• data-cropped="true": Use this if the thumbnail image is cropped.
• An <img> tag inside the link: Used as a thumbnail to be displayed before the large image loads (controlled by thumbSelector).

PhotoSwipe is designed for modern browsers that support ES6 modules.

• Unsupported Browsers: It may not work in IE11, Opera Mini, UC browser, or older versions of Chrome, Safari, and Firefox.
• Progressive Enhancement: To ensure accessibility in unsupported browsers, always provide an alternative way to view the content (e.g., a direct link to the image). If you use the recommended markup (a link to the image), users in unsupported browsers can still access the large image via the link.
• Fallback Implementation: You can provide a fallback using <script type="nomodule"></script>.

All PhotoSwipe events can be bound directly to the PhotoSwipeLightbox instance using the .on(eventName, callback) method. When the lightbox is open, these events are automatically mapped to the PhotoSwipe core. This allows you to manage lifecycle, animations, and content loading from the lightbox instance.

const lightbox = new PhotoSwipeLightbox({
  // options...
});
lightbox.on('eventName', (eventData) => {
  // handle event
});
lightbox.init();

The loading indicator (a spinning 3/4 circle in the top left) appears only if an image fails to load within a specific timeframe (default is 2 seconds, adjustable via preloaderDelay).

To style the preloader, use CSS to target the .pswp__icn class.

Debugging Tip: To see the preloader permanently for testing/debugging, you can force its opacity via CSS using a custom mainClass.

// Debugging: permanently display preloader
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--perma-preloader',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  mainClass: 'pswp-with-perma-preloader',
});
lightbox.init();

/* debug: permanently display preloader */
.pswp-with-perma-preloader .pswp__icn {
  opacity: 0.85 !important;
}

To run the documentation and demo website with automatic rebuilding (watch mode) during development, follow these two steps:

1. Install dependencies for the demo website:

   cd demo-docs-website
   npm install

2. Start the watch process from the root directory:

   npm run watch

# Step 1: In demo-docs-website/
npm install

# Step 2: In root/
npm run watch