PhotoSwipe JavaScript Image Gallery

Common errors

• Uncaught TypeError: PhotoSwipeLightbox is not a constructor

  cause Attempting to use `PhotoSwipeLightbox` before it's properly imported or available in the global scope (e.g., CommonJS `require` in an ESM context, incorrect script tag order, or using the wrong import path).
  fix Ensure you are using `import PhotoSwipeLightbox from 'photoswipe/lightbox';` for ESM setups or loading the correct script files in the browser. Verify your bundler configuration if applicable.

• Uncaught SyntaxError: Unexpected token '??' or 'Uncaught SyntaxError: Unexpected token '.'

  cause Running PhotoSwipe v5.0.0-v5.3.9 in an older browser environment that does not support ES2020 features like nullish coalescing (??) or optional chaining (?).
  fix Upgrade to PhotoSwipe v5.4.0 or newer, which includes fixes for these syntax issues. Alternatively, ensure your build pipeline transpiles modern JavaScript to an ES version supported by your target browsers.

• Gallery not opening or images not loading after click

  cause Incorrect `gallery` or `children` selectors in `PhotoSwipeLightbox` initialization, or `pswpModule` callback not correctly returning the core PhotoSwipe module.
  fix Double-check that the `gallery` and `children` selectors accurately match your HTML structure. Ensure the `pswpModule` option is correctly set up as a dynamic import: `pswpModule: () => import('photoswipe')`.

Warnings

• breaking PhotoSwipe v5 introduces a complete rewrite with a new API and modular structure, making it incompatible with v4. Projects migrating from v4 will require significant code changes.
  Fix: Refer to the official PhotoSwipe v5 documentation for migration guides and new API usage patterns.
• gotcha Early versions of PhotoSwipe v5 (pre-5.4.0) used modern JavaScript syntax like nullish coalescing (??) and optional chaining (?), which caused `SyntaxError`s in older browsers that do not support ES2020 features.
  Fix: Upgrade to PhotoSwipe v5.4.0 or newer. If stuck on an older version, ensure your build process transpiles to a compatible ES version for your target browsers.
• gotcha Accessibility features like ARIA attributes and focus trapping were incrementally improved. Prior to v5.3.4, the gallery might have lacked full ARIA compliance or proper focus management for keyboard navigation.
  Fix: Upgrade to v5.3.4 or later to benefit from improved accessibility. The `trapFocus` option was added in v5.4.1 for further control.
• gotcha A regression in v5.3.5 caused the gallery to lazy-load the full image from `src` instead of correctly utilizing `srcset` for responsive image loading, potentially leading to increased bandwidth usage.
  Fix: Upgrade to PhotoSwipe v5.3.6 or newer to resolve the `srcset` lazy-loading issue.
• deprecated The `dataSource` parameter for `PhotoSwipeLightbox.loadAndOpen` was made optional in v5.4.2. In previous versions, omitting it would lead to an error or unexpected behavior, as it was a required argument.
  Fix: When using versions prior to 5.4.2, always provide a valid `dataSource` array or gallery index to `loadAndOpen`. For 5.4.2+, it defaults to the first gallery if not provided.

Install

• npm install photoswipe npm
• yarn add photoswipe yarn
• pnpm add photoswipe pnpm

Imports

• PhotoSwipeLightbox
  wrong:

  const PhotoSwipeLightbox = require('photoswipe/lightbox');

  correct:

  import PhotoSwipeLightbox from 'photoswipe/lightbox';

  The primary entry point for managing galleries and opening them on user interaction. Used for creating a lightbox instance and attaching it to elements.
• PhotoSwipe
  wrong:

  const PhotoSwipe = require('photoswipe');

  correct:

  import PhotoSwipe from 'photoswipe';

  The core PhotoSwipe module, often dynamically imported by `PhotoSwipeLightbox` via the `pswpModule` option to reduce initial bundle size.
• photoswipe.css

  import 'photoswipe/photoswipe.css';

  Essential CSS styles for the PhotoSwipe gallery to function correctly. Must be imported or linked separately.
• PhotoSwipeOptions

  import type { PhotoSwipeOptions } from 'photoswipe';

  TypeScript type for configuring the core PhotoSwipe instance.

Quickstart

Demonstrates how to set up a basic PhotoSwipe gallery with multiple images using HTML data attributes and initialize the lightbox.

import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/photoswipe.css';

// 1. Define your gallery items in HTML with data attributes
//    <div id="my-gallery">
//      <a href="full-image-1.jpg" data-pswp-width="1200" data-pswp-height="800" target="_blank">
//        <img src="thumbnail-1.jpg" alt="Image 1">
//      </a>
//      <a href="full-image-2.jpg" data-pswp-width="1000" data-pswp-height="1500" target="_blank">
//        <img src="thumbnail-2.jpg" alt="Image 2">
//      </a>
//    </div>

// 2. Initialize the PhotoSwipe Lightbox
const lightbox = new PhotoSwipeLightbox({
  gallery: '#my-gallery',       // Selector for the gallery container
  children: 'a',                // Selector for individual gallery items
  pswpModule: () => import('photoswipe'), // Dynamically import the core module
  
  // Optional: Set options for the core PhotoSwipe instance
  // easing: 'cubic-bezier(.175, .885, .32, 1.275)',
  // bgOpacity: 0.9,
});

// 3. Initialize the lightbox
lightbox.init();

// To open programmatically:
// lightbox.loadAndOpen(0); // Opens the first item