Building Beautiful Photo Galleries

One of s:CMS’s most powerful features is its Gallery component, which combines Astro’s image optimization with PhotoSwipe’s beautiful lightbox experience.

Why Use the Gallery Component?

✅ Automatic image loading from folders
✅ Responsive grid that adapts to screen sizes
✅ Full-screen lightbox with zoom and pan
✅ Custom captions via JSON files
✅ Optimized performance with lazy loading
✅ Keyboard navigation and accessibility

Basic Usage

The simplest way to create a gallery is to place images in a folder and auto-load them:

1
---
2
import { GalleryMdx } from '@core/components/Gallery';
3

4
export const images = import.meta.glob('./gallery/*.{jpg,png,webp}', { eager: true });
5
---
6

7
<GalleryMdx images={images} client:idle />

That’s it! The component will:

1. Find all images in the gallery/ folder
2. Generate optimized versions
3. Create a responsive grid
4. Add lightbox functionality

Live Example

Here’s a working gallery with 3 sample images. Click any image to open the lightbox:

Custom Grid Configuration

Control the grid layout with the columns prop:

1
<GalleryMdx
2
  images={images}
3
  columns={{ min: 200, max: 3 }}
4
  client:idle
5
/>

• min: Minimum item width in pixels (default: 200)
• max: Maximum number of columns (default: 1)

The grid automatically adapts between these values based on screen width!

Adding Custom Captions

Create a captions.json file next to your images:

1
{
2
  "children-593313_1280.jpg": "Two excited children raising their hands in joy",
3
  "coffee-7567749_1280.jpg": "A perfect cappuccino with beautiful latte art",
4
  "laptop-1478822_1280.jpg": "Modern workspace setup with laptop and accessories"
5
}

Then load it in your MDX:

1
import { processGalleryImages } from '@core/components/Gallery';
2

3
export const images = import.meta.glob('./gallery/*.jpg', { eager: true });
4
export const captionsData = import.meta.glob('./gallery/captions.json', { eager: true });
5
export const captions = Object.values(captionsData)[0]?.default;
6

7
<GalleryMdx
8
  images={processGalleryImages(images, { captions })}
9
  client:idle
10
/>

Fuzzy Caption Matching

The Gallery component uses intelligent fuzzy matching for captions. Your caption keys can use any image resolution:

1
{
2
  "photo_1920.jpg": "This works!",
3
  "photo_1280.jpg": "This also works!",
4
  "photo_640.jpg": "All resolutions match!"
5
}

All three keys will match an image file like photo_1280.jpg because the component strips resolution suffixes and matches on the base filename.

Reverse Sorting

By default, images are sorted in descending order by filename. To reverse this:

1
<GalleryMdx
2
  images={processGalleryImages(images, { reverseSorting: true })}
3
  client:idle
4
/>

Using in Astro Files

For .astro files, use the Astro wrapper component:

1
---
2
import { Gallery } from '@core/components/Gallery';
3

4
const imageModules = import.meta.glob('./gallery/*.jpg', { eager: true });
5
const images = processGalleryImages(imageModules);
6
---
7

8
<Gallery images={images} client:idle />

PhotoSwipe Features

The integrated PhotoSwipe lightbox provides:

• Zoom and pan - Pinch or double-click to zoom
• Swipe navigation - Swipe between images
• Keyboard shortcuts - Arrow keys, ESC, etc.
• Captions overlay - Beautiful caption display
• Responsive - Works perfectly on mobile
• Accessible - Full keyboard and screen reader support

Real-World Example

Check out our Gallery Demo to see all these features in action, including:

• Auto-loaded images from a folder
• Custom captions from JSON
• Responsive 3-column grid
• Full PhotoSwipe integration

Best Practices

1. Optimize images before adding them (recommended max: 2000px width)
2. Use consistent naming for easier caption management
3. Write descriptive captions for accessibility
4. Choose appropriate grid sizes (200-300px min width works well)
5. Use eager loading for above-the-fold galleries
6. Consider lazy loading for galleries further down the page

Ready to create your own stunning galleries? Start building now! 📸