Gallery Component

← Back to Documentation

The Gallery component displays images in a responsive grid layout with PhotoSwipe lightbox functionality. It works the same way in .astro files and MDX content — no import.meta.glob needed in your own page or content file.

Key Features

📸 PhotoSwipe Integration — full-screen lightbox with zoom, pan, and swipe gestures
🔄 Auto-loading — automatically discovers images in a gallery/ subfolder
🔗 Shared galleries — reference one set of images by name from any page
📝 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 — colocated auto-loading

With no props, <Gallery /> loads images from a gallery/ folder next to the current page or content file, and captions from a captions.json in that same folder if present.

This demo loads from ./gallery/*.jpg and ./gallery/captions.json, both colocated with this doc page. (This page’s own file is docs/components/gallery/index.mdx — so the demo images end up at docs/components/gallery/gallery/. The doubled “gallery” is a coincidence of this page documenting the Gallery component itself; a normal article wouldn’t have this.)

1
import { Gallery } from '@lad-sapienza/scms-core/components/Gallery';
2

3
<Gallery />

Productive workspace with coffee and laptop

Modern workspace setup with laptop and accessories

A perfect cappuccino with beautiful latte art

Two excited children raising their hands in joy

📄 View captions.json structure

Place this file in your gallery/ folder to provide custom captions:

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

Tip: keys can be filenames with or without extensions, and can use a different image resolution than the actual file — fuzzy matching strips resolution suffixes. Missing captions fall back to auto-generated ones from the filename. A malformed captions.json is ignored (with a console warning) rather than breaking the build.

Images by Pixabay

With reverse sorting

Images are sorted alphabetically by filename by default. Use reverseSorting to reverse this:

1
<Gallery reverseSorting={true} />

Custom column configuration

Control the responsive grid by specifying minimum item width and maximum columns. The grid adapts between these values based on screen width:

1
<Gallery columns={{ min: 200, max: 3 }} />

Shared gallery, referenced by name

A gallery that isn’t tied to one specific page — put it under src/galleries/<name>/ and reference it with the name prop from anywhere in the site. Useful for a set of images reused across multiple articles.

This demo loads from src/galleries/docs-demo/.

1
<Gallery name="docs-demo" />

Shared across pages via src/galleries/docs-demo/

Explicit images (escape hatch)

For images that don’t live in a local gallery/ folder at all — remote URLs, a Directus-backed data source, a custom order computed at build time — pass an already-built GalleryImage[] array directly via images. This takes precedence over both auto-loading and name, and is the one case with no live demo here since it’s meant for data this docs site doesn’t have (e.g. a remote API).

1
<Gallery
2
  images={[
3
    { src: '/photos/img1.jpg', thumb: '/photos/img1.jpg', width: 1200, height: 800, alt: 'Description', caption: 'My custom caption' },
4
  ]}
5
/>

Folder Structure

Colocated (next to a page or content file):

1
my-post/
2
  index.mdx              ← or index.md, or a flat my-post.mdx
3
  gallery/
4
    photo1.jpg
5
    photo2.jpg
6
    captions.json         ← optional

Shared (referenced by name from any page):

1
src/galleries/
2
  scavi-2024/
3
    photo1.jpg
4
    photo2.jpg
5
    captions.json         ← optional

Known limitation: colocated auto-loading matches the current page’s URL against the folder path on disk. If a content collection entry overrides its slug, or the site is deployed under a non-root base, that match can silently fail to find the folder. Use the name prop (shared galleries) or the explicit images prop as a workaround in that case.

Props API

Prop	Type	Default	Description
`name`	`string`	—	Load a shared gallery from `src/galleries/<name>/`
`images`	`GalleryImage[]`	—	Explicit images — takes precedence over `name` and auto-loading
`reverseSorting`	`boolean`	`false`	Reverse the default alphabetical sort
`columns`	`{ min?: number, max?: number }`	`{ min: 200, max: 1 }`	`min` = minimum item width in px; `max` = maximum column count
`className`	`string`	—	Additional CSS classes

With no images and no name, the component auto-loads from a gallery/ folder colocated with the current page/content file.

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
}