react-image-grid-gallery

React Image Grid Gallery

A simple, easy-to-use, and responsive image gallery component with a lightbox for displaying a grid of images in React apps.

Features

• SEO friendly
• Fullscreen support
• Keyboard accessible
• Mobile responsive
• Lightbox with translucent background
• Set column numbers dynamically or manually
• Customizable styles

Live Demo and Tutorial

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

Installation

This section shows how to install the React Image Grid Gallery package.

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 { ImageGallery } from "react-image-grid-gallery";

const imagesArray = [
  {
    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",
  },
  {
    id: "uniqueid333",
    alt: "Image3's alt text",
    caption: "Image3's description",
    src: "http://example.com/image3.webp",
  },
];

function App() {
  return (
    <ImageGallery
      imagesInfoArray={imagesArray}
      columnCount={"auto"}
      columnWidth={230}
      gapSize={24}
    />
  );
}

Props

Props	Type	Default	Description
imagesInfoArray	array	undefined	(Required) An array of objects containing the following properties: id: (Required) An identification string or number that uniquely identifies each image among other images in the array. alt: (Required) The image's alternative text. caption: (Optional) The image's description. src: (Required) The image's URL.
columnCount	number or keyword (string)	"auto"	(Optional) The number of columns.
columnWidth	number or keyword (string)	230	(Optional) The minimum width of the gallery's columns.
gapSize	number	24	(Optional) The gallery's gap size.
fixedCaption	boolean	false	(Optional) Specify whether to display the image captions permanently (true) or to hide them by default and ease them in on mouse hover (false).
customStyles	ImageGalleryStylesType	{}	(Optional) Custom styles to override the following element's default styles: Gallery container: galleryContainerStyle Gallery image button: imageBtnStyle Gallery image container: imageContainerStyle Gallery image element: imageStyle Gallery image caption: imageCaptionStyle Modal container: modalContainerStyle Modal slide number: modalSlideNumberStyle Modal toolbar: modalToolbarStyle Modal toolbar button: modalToolbarBtnStyle Modal slideshow section: modalSlideShowSectionStyle Modal image element: modalImageStyle Modal slide button: modalSlideBtnStyle

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 { 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().

Note for Docusaurus users

Did you get a ReferenceError: crypto is not defined error during the build step? If so, this note is for you.

Wrap the ImageGallery component in <BrowserOnly> if you get a ReferenceError: crypto is not defined error during your build step.

import BrowserOnly from "@docusaurus/BrowserOnly";

function YourComponent() {
  return (
    <BrowserOnly fallback={<div>Loading...</div>}>
      {() => {
        const ImageGallery = require("react-image-grid-gallery").ImageGallery;
        return (
          <ImageGallery
            imagesInfoArray={imagesArray}
            columnCount={"auto"}
            columnWidth={230}
            gapSize={24}
          />
        );
      }}
    </BrowserOnly>
  );
}

This process is essential if your imagesArray uses the Web Crypto API. The <BrowserOnly> component tells Docusaurus to render the ImageGallery library only in the browser. It ensures that the Crypto API runs only in CSR (Client-Side Rendering) rather than during build or SSR (Server-Side Rendering).

Build

npm run build

YouTube Demo

React Image Grid Gallery Demo

Support

🍵 Buy me a coffee

Changelog

3.0.0 (2025-01-09)

• build: Bump dependencies (2e1692e)
• build: Bump typescript from v5.7.2 to v5.7.3 (8811f95)
• docs: Add features section (e4dcb2a)
• docs: Add id property to imagesArray (53816a5)
• docs: Update customStyles' default value to an empty object (d5a311a)
• docs: Update docusaurus note to reflect that crypto is no longer used by default (d11c168)
• style: Specify the gallery images' initial aspect ratio (5b55263)
• refactor: Apply suggestions from code review (bc176a5)
• refactor: Create imageElementsArray from a function (ac645e9)
• refactor: Use empty object as customStyles' default value to reflect the accepted data type (83c6e09)
• Adding configurable styles, key for images, and visibility of captions (effbbc4)
• feat!: Make an id field part of the required properties of the imagesInfoArray prop (0614ed9)
• refactor!: Show error message if id property is missing in the imagesArray (0c05380)
• test: Customize image button's style (5db32f6)
• fix: Change imagesrc's initial value from an empty string to undefined (906d533)
• chore: Reconfigure husky (7c34c74)