Skip to content
Get packs

Guide · Open source

How to use PhotoSwipe: install, build and set up a lightbox

Updated · written with AI from the project's own documentation and checked against our catalogue data

PhotoSwipe is an open-source JavaScript library that shows images in a full-screen lightbox overlay, the viewer that opens when you click a photo on a website. It is described as modular and framework independent, so it does not require React, Vue or another specific framework. This guide explains what you need, how to build the project from its repository, where the main files are, and where to find the documentation to continue.

PhotoSwipedimsemenov/PhotoSwipe · ★ 25.3k · MIT

Quick start

  1. 1Check prerequisites. Install Node.js and npm on your machine.
  2. 2Get the source. Clone or download the PhotoSwipe repository from GitHub.
  3. 3Build the files. From the repository root, run npm run build to create JS and CSS in dist/.
  4. 4Review the layout. Look at src/js/photoswipe.js and src/js/lightbox/lightbox.js to see the entry points.
  5. 5Open the docs. Read the getting-started documentation on photoswipe.com for the v5 API.
  6. 6Try the demo. Visit the demo on photoswipe.com to see the lightbox on mobile and desktop.

What PhotoSwipe is and who it suits

PhotoSwipe is a JavaScript image gallery and lightbox. The project describes it as modular and framework independent, and the README says it is aimed at mobile and desktop use.

It is a good fit for web developers who want a photo gallery on a site, for sites that need touch-friendly image viewing, and for teams that want an MIT-licensed dependency. It is not a no-code tool: you need to write and build JavaScript to use it.

  • Use it if you are comfortable with JavaScript and a build step.
  • Pick something else if you need a no-code gallery builder.
  • The README points to v4 docs separately and describes v5 as the current version, so use the v5 documentation for new work.

What you need before you start

The README lists Node.js and npm as prerequisites for building from source or running the demo website. Install both before you continue.

The README gives few details beyond this, so check the project documentation for anything else your setup requires.

  • Node.js
  • npm

Get the PhotoSwipe source and build it

Clone or download the repository from GitHub. From the repository root, the README says to build the JavaScript and CSS into the dist/ directory with a single command.

Running the build creates the files in dist/, which is the main output folder of the project.

  • Run the build from the repository root, not from a subfolder.
  • The build output goes to dist/ (main JS and CSS).
npm run build

Know the repository layout

The README describes the folders you are most likely to look at. The entry points are in src/, and the documentation is in docs/.

If you want to run the demo website with automatic rebuilds during development, the README says to run npm install in demo-docs-website/ and then npm run watch in the root directory.

  • dist/ - main JS and CSS
  • src/js/photoswipe.js - entry for PhotoSwipe Core
  • src/js/lightbox/lightbox.js - entry for PhotoSwipe Lightbox
  • docs/ - documentation markdown files
  • demo-docs-website/ - website with documentation, demos and manual tests
  • build/ - rollup build config
npm install npm run watch

Find the documentation and demos

The project website hosts a demo and the main documentation. The getting-started page is the place to begin learning the API before writing your own gallery code.

Older v4 documentation is separate. Use it only if you are maintaining an existing v4 setup, and check the repository tags for the old code.

  • Demo: https://photoswipe.com
  • Documentation: https://photoswipe.com/getting-started/
  • v4 docs: https://photoswipe.com/v4-docs/getting-started.html

Check the project status and feedback

The README notes that a new version, PhotoSwipe v6, is in development and asks for feedback in a GitHub discussion. If you are starting a long-lived project, read that discussion to understand what may change.

The project is also tested with BrowserStack, according to the README.

What people use it for

  • Adding a full-screen lightbox to a photo gallery on a website
  • Letting visitors view product images with touch gestures on phones
  • Adding image viewing to a site that does not use React, Vue or another framework
  • Using an MIT-licensed image viewer as a dependency in a commercial project

Frequently asked questions

Is PhotoSwipe free to use?

PhotoSwipe is listed under the MIT licence. The README states this, so you can use it under those terms. Read the LICENSE file in the repository for the full wording.

Do I need a framework to use PhotoSwipe?

No. The project describes itself as framework independent, so it can be added to a page without React, Vue or a similar framework. You still need to write JavaScript to set it up.

How do I install PhotoSwipe?

The README describes building from source: clone the repository and run npm run build from the root to create the files in dist/. It lists Node.js and npm as prerequisites. The README does not give a separate package install command, so check the documentation for that.

Is PhotoSwipe v5 or v4?

The README describes v5 as the current version and points to separate v4 documentation. A v6 is under development, and the README asks for feedback on it. Use the v5 docs for new projects.

What are alternatives to PhotoSwipe?

Projects named as comparable in this directory include Fancybox, Lightbox2, GLightbox and Magnific Popup. Compare them on licence, framework support and the features you need, since the PhotoSwipe README gives few capability details.

Does PhotoSwipe work on mobile?

The project describes itself as a gallery for mobile and desktop, and the README says it is tested with BrowserStack. Test the lightbox on the devices your visitors use before launch.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PhotoSwipe suits developers who want an MIT-licensed, framework-independent lightbox with mobile support and are happy to write and build JavaScript. It is not the right choice for people who need a no-code tool, who must use the old v4 API, or who need specific capabilities that the README does not describe, in which case compare it with Fancybox, GLightbox or the other listed alternatives.

Install options & downloads