Registry / web-framework / react-image-gallery

react-image-gallery

library2.1.2jsnpmunverified

react-image-gallery is a feature-rich, responsive image gallery component designed for React applications. Currently stable at version 2.1.2, it receives regular patch updates, indicating active maintenance. Key capabilities include native mobile swipe gestures, customizable thumbnails with various positioning options, browser or CSS-based fullscreen modes, comprehensive keyboard navigation, and built-in RTL support. It distinguishes itself by offering extensive customization via CSS custom properties and the ability to render custom content like videos or iframes within slides. The library aims to provide a robust and flexible solution for displaying image carousels, supporting modern React versions from 16 through 19 via peer dependencies, and ships with TypeScript types for an enhanced developer experience.

web-framework

npm install react-image-gallery

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-IMAGE-GALLER

react-image-gallery

web-frameworkjavascriptv2.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ImageGallery

✓ import ImageGallery from 'react-image-gallery';

✗ const ImageGallery = require('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

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

✗ import { 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

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

✗ import { 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.

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;

Debug

Known issues

breakingStarting 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.

affects: >=2.1.0

gotchaWhen 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';`

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaEnsure 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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')

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'.

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.

Upgrade

Version history

2.1.2latest on npm

Audit

Dependencies

reactrequiredPeer dependency for rendering React components.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/xiaolin/react-image-gallery ↗

packagehttps://www.npmjs.com/package/react-image-gallery ↗