Quick start

Install

npm

npm install react-pic-gallery

pnpm

pnpm add react-pic-gallery

Yarn

yarn add react-pic-gallery

Bun

bun add react-pic-gallery

React 18.3+ and React 19 are supported.

Create image data

src and alt are required. Add thumbnailSrc when the thumbnail should be a smaller or separately optimized asset.

import type { GalleryImage } from 'react-pic-gallery'

const images: GalleryImage[] = [
  {
    src: 'https://example.com/mountain-large.jpg',
    thumbnailSrc: 'https://example.com/mountain-thumb.jpg',
    alt: 'A mountain reflected in a lake',
    caption: 'Morning at the lake'
  }
]

Image objects can include application-specific fields. Use a generic image type when custom renderers need those fields.

Render the default gallery

import { PicGallery } from 'react-pic-gallery'
import 'react-pic-gallery/styles.css'

export function App() {
  return <PicGallery images={images} />
}

The default gallery provides:

• Responsive thumbnails with native lazy loading.
• An image-focused lightbox with captions and image count.
• Previous/next controls, Escape-to-close, and arrow-key navigation.
• Focus restoration, focus containment, safe-area spacing, and reduced-motion support.

Choose a layout

Choose grid, justified, or mosaic for a thumbnail layout, or carousel to show one image at a time with inline navigation. For grid-based layouts, use columns for a fixed number of columns or leave it unset for responsive auto-fill. rowHeight accepts CSS values and numeric pixel values; neither option applies to the carousel.

<PicGallery images={images} columns={4} rowHeight='10rem' />