photoswipe

library5.4.4jsnpmunverified

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.

http-networking web-framework

npm install photoswipe

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PHOTOSWIPE

photoswipe

http-networkingjavascriptv5.4.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PhotoSwipeLightbox

✓ import PhotoSwipeLightbox from 'photoswipe/lightbox';

✗ const PhotoSwipeLightbox = require('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

✓ import PhotoSwipe from 'photoswipe';

✗ const PhotoSwipe = require('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.

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

Debug

Known issues

breakingPhotoSwipe 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.

affects: >=5.0.0

gotchaEarly 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.

affects: <5.4.0

gotchaAccessibility 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.

affects: <5.3.4

gotchaA 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.

affects: 5.3.5

deprecatedThe `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.

affects: <5.4.2

Errors

Common errors & fixes

Uncaught TypeError: PhotoSwipeLightbox is not a constructor

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 '.'

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

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')`.

Upgrade

Version history

5.4.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/dimsemenov/Photoswipe ↗

packagehttps://www.npmjs.com/package/photoswipe ↗

homepagehttps://photoswipe.com ↗