React Image Gallery

A responsive, customizable image gallery component for React

▶️ VIEW LIVE DEMO

✨ Features

🚀 Getting Started

npm install react-image-gallery

import { useRef } from "react";
import ImageGallery from "react-image-gallery";
import "react-image-gallery/styles/image-gallery.css";
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/",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
  },
  {
    original: "https://picsum.photos/id/1019/1000/600/",
    thumbnail: "https://picsum.photos/id/1019/250/150/",
  },
];

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

  return (
    <ImageGallery
      ref={galleryRef}
      items={images}
      onSlide={(index) => console.log("Slid to", index)}
    />
  );
}

For more examples, see example/App.jsx

⚙️ Props

• items: (required) Array of objects. Available properties:
• original - image source URL
• thumbnail - thumbnail source URL
• fullscreen - fullscreen image URL (defaults to original)
• originalHeight - image height (html5 attribute)
• originalWidth - image width (html5 attribute)
• loading - "lazy" or "eager" (HTML5 attribute)
• thumbnailHeight - image height (html5 attribute)
• thumbnailWidth - image width (html5 attribute)
• thumbnailLoading - "lazy" or "eager" (HTML5 attribute)
• originalClass - custom image class
• thumbnailClass - custom thumbnail class
• renderItem - Function for custom rendering a specific slide (see renderItem below)
• renderThumbInner - Function for custom thumbnail renderer (see renderThumbInner below)
• originalAlt - image alt
• thumbnailAlt - thumbnail image alt
• originalTitle - image title
• thumbnailTitle - thumbnail image title
• thumbnailLabel - label for thumbnail
• description - description for image
• srcSet - image srcset (html5 attribute)
• sizes - image sizes (html5 attribute)
• bulletClass - extra class for the bullet of the item
• infinite: Boolean, default true - loop infinitely
• lazyLoad: Boolean, default false
• showNav: Boolean, default true
• showThumbnails: Boolean, default true
• thumbnailPosition: String, default bottom - options: top, right, bottom, left
• showFullscreenButton: Boolean, default true
• useBrowserFullscreen: Boolean, default true - if false, uses CSS-based fullscreen
• useTranslate3D: Boolean, default true - if false, uses translate instead of translate3d
• showPlayButton: Boolean, default true
• isRTL: Boolean, default false - right-to-left mode
• showBullets: Boolean, default false
• maxBullets: Number, default undefined - max bullets shown (minimum 3, active bullet stays centered)
• showIndex: Boolean, default false
• autoPlay: Boolean, default false
• disableThumbnailScroll: Boolean, default false - disable thumbnail auto-scroll
• disableKeyDown: Boolean, default false - disable keyboard navigation
• disableSwipe: Boolean, default false
• disableThumbnailSwipe: Boolean, default false
• onErrorImageURL: String, default undefined - fallback image URL for failed loads
• indexSeparator: String, default ' / ', ignored if showIndex is false
• slideDuration: Number, default 550 - slide transition duration (ms)
• swipingTransitionDuration: Number, default 0 - transition duration while swiping (ms)
• slideInterval: Number, default 3000
• slideOnThumbnailOver: Boolean, default false
• slideVertically: Boolean, default false - slide vertically instead of horizontally
• flickThreshold: Number, default 0.4 - swipe velocity threshold (lower = more sensitive)
• swipeThreshold: Number, default 30 - percentage of slide width needed to trigger navigation
• stopPropagation: Boolean, default false - call stopPropagation on swipe events
• startIndex: Number, default 0
• onImageError: Function, callback(event) - overrides onErrorImageURL
• onThumbnailError: Function, callback(event) - overrides onErrorImageURL
• onThumbnailClick: Function, callback(event, index)
• onBulletClick: Function, callback(event, index)
• onImageLoad: Function, callback(event)
• onSlide: Function, callback(currentIndex)
• onBeforeSlide: Function, callback(nextIndex)
• onScreenChange: Function, callback(isFullscreen)
• onPause: Function, callback(currentIndex)
• onPlay: Function, callback(currentIndex)
• onClick: Function, callback(event)
• onTouchMove: Function, callback(event) on gallery slide
• onTouchEnd: Function, callback(event) on gallery slide
• onTouchStart: Function, callback(event) on gallery slide
• onMouseOver: Function, callback(event) on gallery slide
• onMouseLeave: Function, callback(event) on gallery slide
• additionalClass: String, additional class for the root node
• renderCustomControls: Function, render custom controls on the current slide
• renderItem: Function, custom slide rendering
• renderThumbInner: Function, custom thumbnail rendering
• renderLeftNav: Function, custom left nav component
• renderRightNav: Function, custom right nav component
• renderTopNav: Function, custom top nav component (vertical mode)
• renderBottomNav: Function, custom bottom nav component (vertical mode)
• renderPlayPauseButton: Function, custom play/pause button
• renderFullscreenButton: Function, custom fullscreen button
• useWindowKeyDown: Boolean, default true - use window or element for key events

🔧 Functions

The following functions can be accessed using refs

• play(): starts the slideshow
• pause(): pauses the slideshow
• togglePlay(): toggles between play and pause
• fullScreen(): enters fullscreen mode
• exitFullScreen(): exits fullscreen mode
• toggleFullScreen(): toggles fullscreen mode
• slideToIndex(index): slides to a specific index
• getCurrentIndex(): returns the current index

🤝 Contributing

Pull requests should be focused on a single issue. If you're unsure whether a change is useful or involves a major modification, please open an issue first.

• Follow the eslint config
• Comment your code

🛠️ Build the example locally

Requires Node.js >= 18.18

git clone https://github.com/xiaolin/react-image-gallery.git
cd react-image-gallery
npm install
npm start

Then open localhost:8001 in a browser.

📄 License

MIT © Xiao Lin