{"id":11553,"library":"photoswipe","title":"PhotoSwipe JavaScript Image Gallery","description":"PhotoSwipe v5.4.4 is a highly customizable JavaScript image gallery and lightbox designed for touch devices. It supports common features like swiping, zooming, and pan gestures, and includes core and lightbox components for flexible integration. The library maintains an active release cadence, frequently publishing patch and minor versions to address bugs, enhance accessibility, and improve browser compatibility. Key differentiators include robust touch support, a modular architecture allowing for dynamic import of its core, extensive customization options via filters and options, and strong focus on accessibility (ARIA attributes, focus trapping) and offline functionality. It ships with TypeScript types, facilitating modern development workflows. It offers a significant rewrite compared to its v4 predecessor, focusing on modern web standards and modularity.","status":"active","version":"5.4.4","language":"javascript","source_language":"en","source_url":"git://github.com/dimsemenov/Photoswipe","tags":["javascript","gallery","lightbox","photo","image","touch","swipe","zoom","typescript"],"install":[{"cmd":"npm install photoswipe","lang":"bash","label":"npm"},{"cmd":"yarn add photoswipe","lang":"bash","label":"yarn"},{"cmd":"pnpm add photoswipe","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary entry point for managing galleries and opening them on user interaction. Used for creating a lightbox instance and attaching it to elements.","wrong":"const PhotoSwipeLightbox = require('photoswipe/lightbox');","symbol":"PhotoSwipeLightbox","correct":"import PhotoSwipeLightbox from 'photoswipe/lightbox';"},{"note":"The core PhotoSwipe module, often dynamically imported by `PhotoSwipeLightbox` via the `pswpModule` option to reduce initial bundle size.","wrong":"const PhotoSwipe = require('photoswipe');","symbol":"PhotoSwipe","correct":"import PhotoSwipe from 'photoswipe';"},{"note":"Essential CSS styles for the PhotoSwipe gallery to function correctly. Must be imported or linked separately.","symbol":"photoswipe.css","correct":"import 'photoswipe/photoswipe.css';"},{"note":"TypeScript type for configuring the core PhotoSwipe instance.","symbol":"PhotoSwipeOptions","correct":"import type { PhotoSwipeOptions } from 'photoswipe';"}],"quickstart":{"code":"import PhotoSwipeLightbox from 'photoswipe/lightbox';\nimport 'photoswipe/photoswipe.css';\n\n// 1. Define your gallery items in HTML with data attributes\n//    <div id=\"my-gallery\">\n//      <a href=\"full-image-1.jpg\" data-pswp-width=\"1200\" data-pswp-height=\"800\" target=\"_blank\">\n//        <img src=\"thumbnail-1.jpg\" alt=\"Image 1\">\n//      </a>\n//      <a href=\"full-image-2.jpg\" data-pswp-width=\"1000\" data-pswp-height=\"1500\" target=\"_blank\">\n//        <img src=\"thumbnail-2.jpg\" alt=\"Image 2\">\n//      </a>\n//    </div>\n\n// 2. Initialize the PhotoSwipe Lightbox\nconst lightbox = new PhotoSwipeLightbox({\n  gallery: '#my-gallery',       // Selector for the gallery container\n  children: 'a',                // Selector for individual gallery items\n  pswpModule: () => import('photoswipe'), // Dynamically import the core module\n  \n  // Optional: Set options for the core PhotoSwipe instance\n  // easing: 'cubic-bezier(.175, .885, .32, 1.275)',\n  // bgOpacity: 0.9,\n});\n\n// 3. Initialize the lightbox\nlightbox.init();\n\n// To open programmatically:\n// lightbox.loadAndOpen(0); // Opens the first item\n","lang":"typescript","description":"Demonstrates how to set up a basic PhotoSwipe gallery with multiple images using HTML data attributes and initialize the lightbox."},"warnings":[{"fix":"Refer to the official PhotoSwipe v5 documentation for migration guides and new API usage patterns.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.3.4"},{"fix":"Upgrade to PhotoSwipe v5.3.6 or newer to resolve the `srcset` lazy-loading issue.","message":"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.","severity":"gotcha","affected_versions":"5.3.5"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<5.4.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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).","error":"Uncaught TypeError: PhotoSwipeLightbox is not a constructor"},{"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.","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 (?).","error":"Uncaught SyntaxError: Unexpected token '??' or 'Uncaught SyntaxError: Unexpected token '.'"},{"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')`.","cause":"Incorrect `gallery` or `children` selectors in `PhotoSwipeLightbox` initialization, or `pswpModule` callback not correctly returning the core PhotoSwipe module.","error":"Gallery not opening or images not loading after click"}],"ecosystem":"npm"}