React Image Grid Gallery

A responsive React image gallery component with an optional lightbox carousel for displaying image grids in React applications.

Features

• SEO friendly
• Full-screen support
• Keyboard accessible
• Keyboard navigation
• Mobile responsive
• Swipe and gesture navigation
• Carousel-style lightbox
• Lightbox with translucent background
• Thumbnail navigation
• Image captions
• Lazy loading support
• Set column numbers dynamically or manually
• Resolution switching compatible
• Customizable styles

Live Demo and Tutorial

Live demo, installation guide, and walkthrough:

https://codesweetly.com/react-image-grid-gallery

Installation

Install the package with your preferred package manager.

Using npm

npm install react-image-grid-gallery --save

Using yarn

yarn add react-image-grid-gallery

Using pnpm

pnpm add react-image-grid-gallery

Usage

Import the library and its stylesheet, then use it like this:

import { ImageGallery } from "react-image-grid-gallery";
import "react-image-grid-gallery/style.css";

const imagesData = [
  {
    id: "uniqueid111",
    alt: "Image1's alt text",
    caption: "Image1's description",
    src: "http://example.com/image1.jpg",
  },
  {
    id: "uniqueid222",
    alt: "Image2's alt text",
    caption: "Image2's description",
    src: "http://example.com/image2.png",
    thumbSrc: "http://example.com/image2_640.png",
  },
  {
    id: "uniqueid333",
    alt: "Image3's alt text",
    caption: "Image3's description",
    cta: {
      href: "https://example.com",
      rel: "noopener noreferrer",
      target: "_blank",
      text: "Learn more",
    },
    src: "http://example.com/image3.webp?w=2400",
    gridSrc: "http://example.com/image3.webp?w=1280",
    thumbSrc: "http://example.com/image3.webp?w=640",
    srcSet:
      "http://example.com/image3.webp?w=2400 2400w, http://example.com/image3.webp?w=1280 1280w, http://example.com/image3.webp?w=640 640w",
    mediaSizes: "(max-width: 640px) 640w, (max-width: 1024px) 1280w, 2400px",
  },
];

function App() {
  return <ImageGallery imagesData={imagesData} gapSize={24} />;
}

Why import the stylesheet?

The components rely on predefined CSS classes for styling. Importing the stylesheet once ensures consistent styling across the gallery components.

Lightbox Navigation

When the default lightbox is enabled, the gallery provides a carousel-style image viewing experience.

Users can navigate between images using:

• Previous and next controls
• Thumbnail navigation
• Keyboard arrow keys
• Swipe and gesture navigation on supported devices

The current image position is displayed in the lightbox, and the active thumbnail remains synchronized with the displayed image.

Swipe navigation is built into the default lightbox and requires no additional configuration.

Props

(Required) An array of objects containing the following properties:

• id: (Required - string or number) Each image's unique identifying key.
• alt: (Required - string) The image's alternative text.
• caption: (Optional - string) The image's description.
• cta: (Optional - object) Adds a call-to-action link to the image's caption in the lightbox. The cta object accepts:
  • href (string, required): Destination URL.
  • rel (string): Link relationship between the current and the linked document (e.g., noopener noreferrer for security reasons when using _blank).
  • target (string): Where to open the linked document (e.g., _blank for a new tab).
  • text (string, required): CTA label.
• src: (Required - string) Default image URL.
• gridSrc: (Optional - string) Preferred grid image's URL.
• thumbSrc: (Optional - string) Preferred thumbnail image's URL.
• srcSet: (Optional - string) Resolution switching image URLs and sizes.
• mediaSizes: (Optional - string) The media conditions and image sizes that hint the browser on the specific srcSet to display when a media condition is true.

columnCount

columnWidth

(Optional) A function to be executed when an image is clicked, if enableDefaultLightbox is false. This allows you to implement your own custom lightbox or any other action on image click.

The customizeImageClickAction function receives two arguments, imageData and index, which are automatically provided. These arguments give you access to the data of the clicked image.

Example 1:

<ImageGallery
  imagesData={imagesData}
  enableDefaultLightbox={false}
  customizeImageClickAction={() => {
    console.log("Image clicked!");
  }}
/>

Example 2:

<ImageGallery
  imagesData={imagesData}
  enableDefaultLightbox={false}
  customizeImageClickAction={(imageData, index) => {
    console.log("Image clicked:", imageData, index);
  }}
/>

note: The customizeImageClickAction feature is not compatible with the Astro framework, as Astro does not support passing functions to hydrated components.

(Optional) Specify whether to use the package’s default lightbox. If set to false, you can use the customizeImageClickAction prop to implement your own lightbox or any other action when an image is clicked.

(Optional) Specify whether to display the image captions permanently (true) or to hide them by default and ease them in on mouse hover (false).

gapSize

(Optional) The image's index to begin the grid's lazy loading.

tip: Use a negative number to lazy load all the images.

Note for Remix Users

Remix users should add "react-image-grid-gallery" to their remix.config.js file:

/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  ignoredRouteFiles: ["**/.*"],
+ serverDependenciesToBundle: ["react-image-grid-gallery"],
  serverModuleFormat: "cjs",
};

The serverDependenciesToBundle field tells Remix to transpile and include the "react-image-grid-gallery" package in the server bundle.

Note for NextJS users

NextJS users should declare the "use client" directive at the top of their file. It should sit above all other import statements like so:

+ "use client";
import { ImageGallery } from "react-image-grid-gallery";
import "react-image-grid-gallery/style.css";
import { YouTubePlaylist } from "@codesweetly/react-youtube-playlist";

The "use client" directive tells NextJS to consider all modules imported into the page as part of the Client Component module graph.

The ImageGallery package works only as a Client Component because it uses React's State and Lifecycle effects, such as useState() and useEffect().

Browser-Only APIs and Static Rendering

If your imagesData uses browser-only APIs such as the Web Crypto API (for example, crypto.randomUUID() to generate image IDs), you may need to ensure that the code generating those values runs only in the browser when using a framework or static site generator that performs server-side rendering (SSR) or static rendering (SSG).

Example:

const imagesData = [
  {
    id: crypto.randomUUID(),
    alt: "A beautiful landscape",
    src: "/images/landscape.jpg",
  },
];

If your framework attempts to evaluate browser-only APIs during server-side rendering or the build process, you may encounter errors such as ReferenceError: crypto is not defined.

In such cases, follow your framework's recommended approach for deferring browser-only code to client-side execution.

Note: react-image-grid-gallery does not require the Web Crypto API. This consideration applies only when your application uses browser-only APIs while creating or processing the data passed to the gallery.

Build

npm run build

YouTube Demo

React Image Grid Gallery Demo

Contributing

Contributions, bug reports, and suggestions are welcome and appreciated.

If you find an issue or have an improvement to propose, please open an issue or submit a pull request.

For larger changes, it is helpful to open an issue first so we can discuss the proposed direction before implementation.

Need help?

Need help integrating this package, customizing the gallery, or solving a frontend implementation issue?

See Let's build on CodeSweetly.

Support

🍵 Buy me a coffee