{"id":11722,"library":"react-image-gallery","title":"React Image Gallery","description":"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.","status":"active","version":"2.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/xiaolin/react-image-gallery","tags":["javascript","react","carousel","react-component","react-carousel","react-slideshow","react-gallery","react carousel","react slideshow","typescript"],"install":[{"cmd":"npm install react-image-gallery","lang":"bash","label":"npm"},{"cmd":"yarn add react-image-gallery","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-image-gallery","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for rendering React components.","package":"react","optional":false}],"imports":[{"note":"This is the default export for the main gallery component. CommonJS `require` syntax is not the recommended approach for modern React applications using ESM.","wrong":"const ImageGallery = require('react-image-gallery');","symbol":"ImageGallery","correct":"import ImageGallery from 'react-image-gallery';"},{"note":"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.","wrong":"import { GalleryItem } from 'react-image-gallery';","symbol":"GalleryItem","correct":"import type { GalleryItem } from 'react-image-gallery';"},{"note":"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`.","wrong":"import { ImageGalleryRef } from 'react-image-gallery';","symbol":"ImageGalleryRef","correct":"import type { ImageGalleryRef } from 'react-image-gallery';"},{"note":"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.","symbol":"CSS Stylesheet","correct":"import 'react-image-gallery/styles/image-gallery.css';"}],"quickstart":{"code":"import { useRef } from \"react\";\nimport ImageGallery from \"react-image-gallery\";\nimport \"react-image-gallery/styles/image-gallery.css\"; // Essential for styling since v2.1.0\nimport type { GalleryItem, ImageGalleryRef } from \"react-image-gallery\";\n\nconst images: GalleryItem[] = [\n  {\n    original: \"https://picsum.photos/id/1018/1000/600/\",\n    thumbnail: \"https://picsum.photos/id/1018/250/150/\",\n    description: \"A beautiful mountain landscape\"\n  },\n  {\n    original: \"https://picsum.photos/id/1015/1000/600/\",\n    thumbnail: \"https://picsum.photos/id/1015/250/150/\",\n    description: \"A calm lake with boats\"\n  },\n  {\n    original: \"https://picsum.photos/id/1019/1000/600/\",\n    thumbnail: \"https://picsum.photos/id/1019/250/150/\",\n    description: \"City skyline at sunset\"\n  },\n];\n\nfunction MyGallery() {\n  const galleryRef = useRef<ImageGalleryRef>(null);\n\n  return (\n    <div style={{ maxWidth: '800px', margin: 'auto', padding: '20px' }}>\n      <h2>My Awesome Image Gallery</h2>\n      <ImageGallery\n        ref={galleryRef}\n        items={images}\n        onSlide={(index) => console.log(\"Slid to\", index)}\n        showFullscreenButton={true}\n        showPlayButton={true}\n        lazyLoad={true}\n        thumbnailPosition=\"bottom\"\n      />\n      <button onClick={() => galleryRef.current?.slideToIndex(0)} style={{ marginTop: '15px' }}>\n        Go to First Slide\n      </button>\n    </div>\n  );\n}\n\nexport default MyGallery;","lang":"typescript","description":"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."},"warnings":[{"fix":"Add `import 'react-image-gallery/styles/image-gallery.css';` to your main application file or component where the gallery is used.","message":"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.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Use `const galleryRef = useRef<ImageGalleryRef>(null);` and ensure `ImageGalleryRef` is imported as a type: `import type { ImageGalleryRef } from 'react-image-gallery';`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that each object in the `items` array conforms to the `GalleryItem` interface, at minimum providing `original` and `thumbnail` string URLs.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The CSS stylesheet for the gallery component is missing its import statement, or the path is incorrect.","error":"Module not found: Can't resolve 'react-image-gallery/styles/image-gallery.css'"},{"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`.","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.","error":"TypeError: Cannot read properties of null (reading 'current')"},{"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.","cause":"Image `original` or `thumbnail` properties within `items` array are `undefined` or not correctly typed as `string` when they are expected to be.","error":"TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'."}],"ecosystem":"npm"}