Image Gallery

A responsive grid of images with an interactive lightbox viewer featuring zoom, keyboard navigation, and thumbnail strip.

Basic

A responsive grid of images with an interactive lightbox viewer featuring zoom, keyboard navigation, and thumbnail strip. Click any image to open the lightbox.

<ImageGallery
images={[
  { src: "/photo-1.jpg", alt: "Mountain landscape", caption: "Dolomites" },
  { src: "/photo-2.jpg", alt: "Sunlit valley", caption: "Golden Valley" },
  { src: "/photo-3.jpg", alt: "Forest path", caption: "Ancient Trail" },
  { src: "/photo-4.jpg", alt: "Waterfall", caption: "Hidden Waterfall" },
  { src: "/photo-5.jpg", alt: "Sunset lake", caption: "Sunset Reflections" },
  { src: "/photo-6.jpg", alt: "Misty hills", caption: "Morning Mist" },
]}
columns={3}
aspectRatio="video"
/>

<ImageGalleryimages={[  { src: "/photo-1.jpg", alt: "Mountain landscape", caption: "Dolomites" },  { src: "/photo-2.jpg", alt: "Sunlit valley", caption: "Golden Valley" },  { src: "/photo-3.jpg", alt: "Forest path", caption: "Ancient Trail" },  { src: "/photo-4.jpg", alt: "Waterfall", caption: "Hidden Waterfall" },  { src: "/photo-5.jpg", alt: "Sunset lake", caption: "Sunset Reflections" },  { src: "/photo-6.jpg", alt: "Misty hills", caption: "Morning Mist" },]}columns={3}aspectRatio="video"/>

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add image-gallery

pnpm dlx @work-rjkashyap/unified-ui add image-gallery

npx @work-rjkashyap/unified-ui add image-gallery

bunx @work-rjkashyap/unified-ui add image-gallery

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { ImageGallery } from "@work-rjkashyap/unified-ui";

Examples

Columns

2 columns

4 columns

{/* 2 columns */}
<ImageGallery images={images} columns={2} />

{/* 4 columns */}

<ImageGallery images={images} columns={4} />

{/* 2 columns */}<ImageGallery images={images} columns={2} />{/* 4 columns */}<ImageGallery images={images} columns={4} />

Aspect Ratios

square

video (16:9)

{/* Square thumbnails */}
<ImageGallery images={images} columns={3} aspectRatio="square" />

{/* 16:9 thumbnails */}

<ImageGallery images={images} columns={3} aspectRatio="video" />

{/* Natural aspect ratio */}

<ImageGallery images={images} columns={3} aspectRatio="auto" />

{/* Square thumbnails */}<ImageGallery images={images} columns={3} aspectRatio="square" />{/* 16:9 thumbnails */}<ImageGallery images={images} columns={3} aspectRatio="video" />{/* Natural aspect ratio */}<ImageGallery images={images} columns={3} aspectRatio="auto" />

Custom Gap

gap=2

gap=16

{/* Tight gap */}
<ImageGallery images={images} columns={3} gap={2} />

{/* Spacious gap */}

<ImageGallery images={images} columns={3} gap={16} />

{/* Tight gap */}<ImageGallery images={images} columns={3} gap={2} />{/* Spacious gap */}<ImageGallery images={images} columns={3} gap={16} />

With Captions

<ImageGallery
images={[
  { src: "/photo-1.jpg", alt: "Mountain lake", caption: "Mountain Lake — Dolomites, Italy" },
  { src: "/photo-2.jpg", alt: "Sunlit valley", caption: "Golden Valley — Swiss Alps" },
  { src: "/photo-3.jpg", alt: "Forest path", caption: "Ancient Forest — Pacific Northwest" },
]}
columns={3}
/>

<ImageGalleryimages={[  { src: "/photo-1.jpg", alt: "Mountain lake", caption: "Mountain Lake — Dolomites, Italy" },  { src: "/photo-2.jpg", alt: "Sunlit valley", caption: "Golden Valley — Swiss Alps" },  { src: "/photo-3.jpg", alt: "Forest path", caption: "Ancient Forest — Pacific Northwest" },]}columns={3}/>

Single Image

Props

Prop	Type	Default	Description
`images`	`GalleryImage[]`	—	Array of images to display.
`columns`	`1 \| 2 \| 3 \| 4`	`3`	Number of grid columns.
`gap`	`number`	`8`	Gap between grid items in pixels.
`aspectRatio`	`"square" \| "video" \| "auto"`	`"square"`	Aspect ratio for thumbnails.
`lightbox`	`boolean`	`true`	Whether to enable the lightbox on click.
`className`	`string`	—	Additional CSS classes on the grid.
`renderThumbnail`	`(image, index) => ReactNode`	—	Custom thumbnail renderer.

GalleryImage

Property	Type	Description
`src`	`string`	Image source URL.
`alt`	`string`	Alt text for accessibility.
`thumbnail`	`string`	Optional thumbnail URL (falls back to src).
`caption`	`string`	Optional caption shown in lightbox.

Key	Action
`←` / `→`	Previous / Next image
`Escape`	Close lightbox
Click image	Toggle zoom

Accessibility

Grid uses role="group" with aria-label.
Lightbox uses role="dialog" with aria-modal.
All images require alt text for screen readers.
Full keyboard navigation support in lightbox.
Thumbnail strip buttons use aria-current for the active image.
Respects prefers-reduced-motion — animations are disabled when the user prefers reduced motion.

Always provide descriptive alt text for each image. Captions are optional but recommended for galleries with meaningful content.

Design Tokens

Token	Usage
`--border`	Thumbnail border
`--muted`	Thumbnail background
`--radius-lg`	Thumbnail border radius
`--shadow-md`	Hover shadow on thumbnails
`--duration-fast`	Transition speed