react-masonry-lightbox

A simple, responsive React masonry gallery with a built-in lightbox. No CSS file to import, no config required — install it and it just works.

• 📱 Responsive out of the box: set columns for mobile, tablet, and desktop
• 🖼️ Built-in lightbox with keyboard nav (←/→/Esc), click-to-close, and captions
• 🎯 Beginner-friendly: one component, sensible defaults, zero setup
• 📦 Tiny, ships ESM + CJS + TypeScript types
• ♿ Accessible: focus-visible states, aria labels, keyboard support

Install

npm install react-masonry-lightbox

Quick start

import { MasonryGallery } from "react-masonry-lightbox";

const images = [
  { src: "/photos/1.jpg", alt: "Mountain sunrise" },
  { src: "/photos/2.jpg", alt: "City skyline" },
  { src: "/photos/3.jpg", alt: "Beach at sunset" },
  // ...
];

function Gallery() {
  return <MasonryGallery images={images} />;
}

That's it — no CSS import, no extra setup. Clicking an image opens it in a fullscreen lightbox with next/previous navigation.

Responsive columns

By default the gallery shows 1 column on mobile, 2 on tablet, 3 on desktop. Override any of these:

<MasonryGallery
  images={images}
  columns={{ mobile: 1, tablet: 3, desktop: 5 }}
/>

You can also change the pixel widths where it switches between sizes:

<MasonryGallery
  images={images}
  columns={{ mobile: 2, tablet: 3, desktop: 4 }}
  breakpoints={{ mobile: 480, tablet: 900 }}
/>

Captions and thumbnails

const images = [
  {
    src: "/photos/1-full.jpg",       // shown in the lightbox
    thumbnail: "/photos/1-thumb.jpg", // shown in the grid (optional, faster loading)
    alt: "Mountain sunrise",
    caption: "Sunrise over the Rockies, June 2026",
  },
];

Disabling the lightbox

If you just want the masonry grid without click-to-expand:

<MasonryGallery images={images} lightbox={false} />

Handling clicks yourself

<MasonryGallery
  images={images}
  onImageClick={(index) => console.log("Clicked image", index)}
/>

onImageClick fires in addition to the lightbox opening (unless lightbox={false}).

Props

| Prop | Type | Default | Description | |---|---|---|---| | images | MasonryImage[] | — | Required. Array of images to display | | columns | { mobile?, tablet?, desktop? } | { 1, 2, 3 } | Column count per screen size | | breakpoints | { mobile?, tablet? } | { 640, 1024 } | Pixel widths where columns switch | | gap | number | 12 | Gap between images, in pixels | | rounded | boolean | true | Rounded corners on images | | lightbox | boolean | true | Open a fullscreen viewer on click | | onImageClick | (index: number) => void | — | Called when an image is clicked | | className | string | — | Extra class name on the container |

MasonryImage

| Field | Type | Description | |---|---|---| | src | string | Required. Full-size image URL (shown in lightbox) | | thumbnail | string | Optional smaller image for the grid | | alt | string | Alt text | | caption | string | Optional caption shown in the lightbox |

License

MIT