React Image Gallery

Common errors

• Module not found: Can't resolve 'react-image-gallery/styles/image-gallery.css'

  cause The CSS stylesheet for the gallery component is missing its import statement, or the path is incorrect.
  fix Add `import 'react-image-gallery/styles/image-gallery.css';` to your application's entry point or the component where `ImageGallery` is used. This is mandatory since `v2.1.0`.

• TypeError: Cannot read properties of null (reading 'current')

  cause Attempting to access `galleryRef.current` before the component has mounted or if the ref is not properly assigned to the `ImageGallery` component, or incorrect TypeScript typing.
  fix Ensure `galleryRef.current` is checked for `null` before access (e.g., `galleryRef.current?.slideToIndex(0)`). Also, verify the ref is passed to `<ImageGallery ref={galleryRef} />` and that `ImageGalleryRef` type is correctly used with `useRef`.

• TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.

  cause Image `original` or `thumbnail` properties within `items` array are `undefined` or not correctly typed as `string` when they are expected to be.
  fix Ensure all `original`, `thumbnail`, and other URL-related properties in your `GalleryItem` array are always strings and not `undefined`. For optional properties, provide a default empty string or handle `undefined` values explicitly.

Warnings

• breaking Starting with `v2.1.0`, the library no longer automatically injects its CSS stylesheet into the DOM. Developers must explicitly import `react-image-gallery/styles/image-gallery.css` in their application. Failure to do so will result in an unstyled or poorly styled gallery. This change improves SSR compatibility and reduces bundle size.
  Fix: Add `import 'react-image-gallery/styles/image-gallery.css';` to your main application file or component where the gallery is used.
• gotcha When programmatically interacting with the gallery (e.g., using `slideToIndex`, `play`, `pause`), it's essential to correctly type the `useRef` hook with `ImageGalleryRef` for accurate TypeScript inference and to avoid potential runtime errors or type mismatches.
  Fix: Use `const galleryRef = useRef<ImageGalleryRef>(null);` and ensure `ImageGalleryRef` is imported as a type: `import type { ImageGalleryRef } from 'react-image-gallery';`
• gotcha The `items` prop expects an array of objects, where each object *must* include an `original` URL for the main image and typically a `thumbnail` URL for the thumbnail. Incorrectly structured `items` arrays can lead to rendering issues, missing images, or unexpected behavior.
  Fix: Verify that each object in the `items` array conforms to the `GalleryItem` interface, at minimum providing `original` and `thumbnail` string URLs.
• gotcha Ensure that image paths provided in the `items` prop are correctly resolved by your build system. Relative paths for local images might require specific handling (e.g., `require()` for static assets or moving them to the `public` folder) depending on your React project setup (e.g., Create React App, Vite).
  Fix: For local images, consider placing them in the `public` folder and using absolute paths like `/images/my-image.jpg`, or importing them explicitly: `import image from './assets/image.jpg';` and using `image` as the source.

Install

• npm install react-image-gallery npm
• yarn add react-image-gallery yarn
• pnpm add react-image-gallery pnpm

Imports

• ImageGallery
  wrong:

  const ImageGallery = require('react-image-gallery');

  correct:

  import ImageGallery from 'react-image-gallery';

  This is the default export for the main gallery component. CommonJS `require` syntax is not the recommended approach for modern React applications using ESM.
• GalleryItem
  wrong:

  import { GalleryItem } from 'react-image-gallery';

  correct:

  import type { GalleryItem } from 'react-image-gallery';

  Import the `GalleryItem` type using `import type` for type safety in TypeScript projects. Omitting `type` can lead to bundle size increases or unexpected behavior in some bundlers.
• ImageGalleryRef
  wrong:

  import { ImageGalleryRef } from 'react-image-gallery';

  correct:

  import type { ImageGalleryRef } from 'react-image-gallery';

  Import the `ImageGalleryRef` type for typing the `useRef` hook when you need programmatic access to the gallery's methods (e.g., `slideToIndex`). Always use `import type`.
• CSS Stylesheet

  import 'react-image-gallery/styles/image-gallery.css';

  Since v2.1.0, the CSS stylesheet is no longer automatically injected and must be explicitly imported. Failure to do so will result in an unstyled or incorrectly styled gallery.

Quickstart

This quickstart demonstrates how to import and use the ImageGallery component with a basic set of images, including TypeScript types for props and refs, and shows an example of programmatic control. It also includes the crucial CSS import for proper styling.

import { useRef } from "react";
import ImageGallery from "react-image-gallery";
import "react-image-gallery/styles/image-gallery.css"; // Essential for styling since v2.1.0
import type { GalleryItem, ImageGalleryRef } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
    description: "A beautiful mountain landscape"
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
    description: "A calm lake with boats"
  },
  {
    original: "https://picsum.photos/id/1019/1000/600/",
    thumbnail: "https://picsum.photos/id/1019/250/150/",
    description: "City skyline at sunset"
  },
];

function MyGallery() {
  const galleryRef = useRef<ImageGalleryRef>(null);

  return (
    <div style={{ maxWidth: '800px', margin: 'auto', padding: '20px' }}>
      <h2>My Awesome Image Gallery</h2>
      <ImageGallery
        ref={galleryRef}
        items={images}
        onSlide={(index) => console.log("Slid to", index)}
        showFullscreenButton={true}
        showPlayButton={true}
        lazyLoad={true}
        thumbnailPosition="bottom"
      />
      <button onClick={() => galleryRef.current?.slideToIndex(0)} style={{ marginTop: '15px' }}>
        Go to First Slide
      </button>
    </div>
  );
}

export default MyGallery;