In this guide, you will learn how to use PhotoSwipe in an Astro application. You will go through the process of setting up a new Astro project, installing the PhotoSwipe module, and turning your images collection into an image gallery.
Prerequisites
You’ll need the following:
- Node.j 20 or later
Table Of Contents
- Create a new Astro application
- Integrate PhotoSwipe in your Astro project
- Build and Test your Astro application locally
- Source Code
- Conclusion
Create a new Astro application
Let’s get started by creating a new Astro project. Execute the following command:
npm create astro@latest my-appnpm create astro is the recommended way to scaffold an Astro project quickly.
When prompted, choose:
Emptywhen prompted on how to start the new project.Yeswhen prompted if plan to write Typescript.Strictwhen prompted how strict Typescript should be.Yeswhen prompted to install dependencies.Yeswhen prompted to initialize a git repository.
Once that’s done, you can move into the project directory and start the app:
cd my-appnpm run devThe app should be running on localhost:4321.
Now, let’s move on to integrate PhotoSwipe in your Astro application.
Integrate PhotoSwipe in your Astro project
Install PhotoSwipe SDK
Execute the command below to install the necessary package for using PhotoSwipe:
npm install photoswipenpm install -D @types/photoswipeThe command installs the following library:
photoswipe: A framework-agnostic JavaScript Image Gallery library.@types/photoswipe: Type definitions forphotoswipelibrary.
Create an Image Collection
Using PhotoSwipe (with the default configuration) requires two things:
- A parent HTML element (most commonly, a
<div>) which contains all the images. - Each image to be enclosed in an
<a>tag containing theheightandwidthattribute of the image.
To make sure that the <a> element does not take over the styling of your <img> elements, you can use the following CSS to only render it’s children elements: display: contents;. In the example below, you are going to use the contents class by Tailwind CSS.
---// File: src/pages/index.astro // [!code focus]import { ViewTransitions } from "astro:transitions";---// [!code focus]<html lang="en"> <head> <meta charset="utf-8" /> <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> <meta name="viewport" content="width=device-width" /> <meta name="generator" content={Astro.generator} /> <title>Astro</title> <ViewTransitions /> </head> <body> <div id="my-gallery" class="grid grid-cols-1 py-10 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"> <a href="https://picsum.photos/900/1600" data-pswp-width="900" data-pswp-height="1600" class="contents"> <img width="900" height="1600" loading="lazy" decoding="async" src="https://picsum.photos/900/1600" class="absolute h-[250px] w-[300px] object-cover shadow-sm" /> </a> <a href="https://picsum.photos/900/1600" data-pswp-width="900" data-pswp-height="1600" class="contents"> <img width="900" height="1600" loading="lazy" decoding="async" src="https://picsum.photos/900/1600" class="absolute h-[250px] w-[300px] object-cover shadow-sm" /> </a> </div> </body></html>Turn your Image Collection into an Image Gallery
In minimal lines of code with PhotoSwipe, you can turn your collection of images into an interactive image gallery. You can easily do that in 3 steps:
- Import the
PhotoSwipecss. - Import the
PhotoSwipemodule. - Create a lightbox using
PhotoSwipe.
Refer to the script below to do the above steps in this example:
---// File: src/pages/index.astro // [!code focus]import { ViewTransitions } from "astro:transitions";---// [!code focus]<html lang="en"> <head> <meta charset="utf-8" /> <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> <meta name="viewport" content="width=device-width" /> <meta name="generator" content={Astro.generator} /> <title>Astro</title> <ViewTransitions /> </head> <body> <div id="my-gallery" class="grid grid-cols-1 py-10 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"> <a href="https://picsum.photos/900/1600" data-pswp-width="900" data-pswp-height="1600" class="contents"> <img width="900" height="1600" loading="lazy" decoding="async" src="https://picsum.photos/900/1600" class="absolute h-[250px] w-[300px] object-cover shadow-sm" /> </a> <a href="https://picsum.photos/900/1600" data-pswp-width="900" data-pswp-height="1600" class="contents"> <img width="900" height="1600" loading="lazy" decoding="async" src="https://picsum.photos/900/1600" class="absolute h-[250px] w-[300px] object-cover shadow-sm" /> </a> </div> <script> import 'photoswipe/style.css' import pswpModule from 'photoswipe' import PhotoSwipeLightbox from 'photoswipe/lightbox'
const lightbox = new PhotoSwipeLightbox({ pswpModule, children: 'a', gallery: '#my-gallery', })
document.addEventListener( 'astro:page-load', () => { if (lightbox) lightbox.init() }, { once: false }, ) </script> </body></html>In the code above you have done the following:
- Imported the
PhotoSwipeCSS. - Created a lightbox that listens to clicks on all the
<a>elements, present hirerachly in the HTML element that hasmy-galleryas it’s id attribute. - Attaches an Astro page load listener and brings the lightbox in effect. This way of instantiating the lightbox is helpful as this script can be used with View Transitions enabled in your Astro application as well.
Build and Test your Astro application locally
To test the application, prepare a build and run the preview server using the command below:
npm run build && npm run previewSource Code
To get everything pre-built as in this guide, please visit https://github.com/rishi-raj-jain/astro-photoswipe-starter.
Conclusion
In this guide, you learned how to use PhotoSwipe in an Astro application to build an Image Gallery.
If you have any questions or comments, feel free to reach out to me on Twitter.
