PhotoSwipe — JavaScript Image Gallery and Lightbox

Introduction

PhotoSwipe is a JavaScript image gallery and lightbox that provides a native-app-like experience on the web. It supports pinch-to-zoom, swipe navigation, and progressive image loading with no dependencies and a small footprint.

What PhotoSwipe Does

• Opens images in a full-screen lightbox overlay with smooth zoom and pan
• Supports swipe gestures for navigation and pinch-to-zoom on touch devices
• Loads images progressively, showing thumbnails first then swapping in full-resolution versions
• Provides a responsive design that adapts to any screen size and orientation
• Handles image captions, sharing controls, and custom toolbar buttons

Architecture Overview

PhotoSwipe v5 uses a modular ES module design. The lightbox module handles gallery initialization and event delegation on thumbnail links. The core module manages the slide viewport, gesture recognition, and zoom state machine. CSS animations power transitions with GPU-accelerated transforms. Images are lazy-loaded on demand, and the dynamic import pattern keeps the initial bundle small until the lightbox is first opened.

Self-Hosting & Configuration

• Install via npm or include from a CDN; import both the JS module and CSS stylesheet
• Mark gallery links with data-pswp-width and data-pswp-height attributes for layout calculation
• Configure options like bgOpacity, zoom, showHideAnimationType, and padding
• Add custom UI elements by extending the lightbox with pswp.ui.registerElement()
• Integrate with frameworks by calling lightbox.init() after the DOM is ready or in a lifecycle hook

Key Features

• Zero dependencies with a ~5KB gzipped core plus dynamically loaded lightbox module
• Native-feeling gestures: pinch-to-zoom, swipe to close, and momentum-based panning
• URL-based deep linking so individual images can be shared and bookmarked
• Accessibility support with keyboard navigation and ARIA labels
• Plugin API for custom slides (video, HTML content) and toolbar extensions

Comparison with Similar Tools

• Lightbox2 — jQuery-based, simpler but no touch gestures or zoom; PhotoSwipe is modern and dependency-free
• GLightbox — Lightweight with video support; PhotoSwipe has better zoom and gesture handling
• Fancybox — Feature-rich but requires a commercial license; PhotoSwipe is MIT-licensed
• Magnific Popup — jQuery plugin, no longer maintained; PhotoSwipe is actively developed
• medium-zoom — Single-image zoom effect; PhotoSwipe provides full gallery navigation

FAQ

Q: Does PhotoSwipe require jQuery? A: No. Version 5 is a standalone ES module with zero dependencies.

Q: Can I display videos in PhotoSwipe? A: Yes. Use the content API to register a custom slide type that renders a video element or iframe inside the lightbox.

Q: How does deep linking work? A: PhotoSwipe updates the URL hash with the current slide index. Users can share the URL to link directly to a specific image in the gallery.

Q: Is PhotoSwipe accessible? A: Yes. It supports full keyboard navigation (arrow keys, Escape to close), focus trapping within the lightbox, and ARIA labels on controls.

Sources

• https://github.com/dimsemenov/PhotoSwipe
• https://photoswipe.com/