The Gallery component displays images in a responsive grid layout with PhotoSwipe lightbox functionality. It automatically loads images from a gallery/ subfolder and supports custom captions, sorting options, and responsive column configuration.

Key Features

• 📸 PhotoSwipe Integration — full-screen lightbox with zoom, pan, and swipe gestures
• 🔄 Auto-loading — automatically discovers images in a gallery/ subfolder
• 📝 Custom Captions — via captions.json or auto-generated from filenames
• 🎨 Responsive Grid — configurable columns that adapt to screen size
• ⌨️ Keyboard Navigation — arrow keys, ESC, and full accessibility support

Live Examples

Default usage with auto-loading

1
// At the top of your MDX file:
2
import { GalleryMdx, processGalleryImages } from '@core/components/Gallery';
3

4
export const galleryImages = import.meta.glob(
5
  './gallery/*.{jpg,jpeg,png,gif,webp,avif}',
6
  { eager: true }
7
);
8
export const captionsData = import.meta.glob('./gallery/captions.json', { eager: true });
9
export const captions = Object.values(captionsData)[0]?.default;
10

11
// In your content:
12
<GalleryMdx
13
  images={processGalleryImages(galleryImages, { captions })}
14
  client:idle
15
/>

1
{
2
  "photo1.jpg": "A short caption for this image",
3
  "photo2.jpg": "Another caption"
4
}

Images by Pixabay

With reverse sorting

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

Custom column configuration

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

Without custom captions (filename-based)

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

Usage in Astro Files

For .astro files, use the Gallery Astro wrapper which handles image loading automatically:

1
---
2
import Gallery from '@core/components/Gallery/Gallery.astro';
3
---
4

5
<Gallery />

The wrapper automatically:

1. Detects the current page path
2. Loads images from a ./gallery/ subfolder (jpg, jpeg, png, gif, webp, avif)
3. Loads captions from ./gallery/captions.json if present
4. Optimizes images at build time via Astro

Folder Structure

Place your images next to your MDX or Astro page file:

1
your-page.mdx            ← or your-page/index.mdx
2
gallery/
3
  photo1.jpg
4
  photo2.jpg
5
  captions.json          ← optional

The import.meta.glob path must be a static string literal relative to the MDX file — variables are not supported.

Props API

GalleryMdx Props

processGalleryImages Options

GalleryImage Type

1
interface GalleryImage {
2
  src: string;       // Full-size image URL
3
  thumb: string;     // Thumbnail URL
4
  width: number;
5
  height: number;
6
  alt: string;
7
  caption?: string;
8
}