react-image-gallery

To use the gallery, import ImageGallery and its required CSS file. Provide an array of GalleryItem objects to the items prop. You can also use a ref with the ImageGalleryRef type to access imperative methods like play() or slideToIndex().

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)}
    />
  );
}

The items prop is a required array of objects. Each object represents a slide and can contain the following 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
• renderThumbInner: Function for custom thumbnail renderer
• 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

The ImageGallery component accepts several props to control its behavior and appearance:

Display & Navigation

• infinite: Boolean, default true - loop infinitely
• showNav: Boolean, default true
• showThumbnails: Boolean, default true
• thumbnailPosition: String, default bottom (top, right, bottom, left)
• showFullscreenButton: Boolean, default true
• useBrowserFullscreen: Boolean, default true - if false, uses CSS-based fullscreen
• showPlayButton: Boolean, default true
• showBullets: Boolean, default false
• maxBullets: Number, default undefined - max bullets shown (minimum 3, active bullet stays centered)
• showIndex: Boolean, default false
• slideVertically: Boolean, default false - slide vertically instead of horizontally
• isRTL: Boolean, default false - right-to-left mode

Autoplay & Transitions

• autoPlay: Boolean, default false
• slideDuration: Number, default 550 (ms)
• slideInterval: Number, default 3000
• swipingTransitionDuration: Number, default 0 (ms)

Interaction & Constraints

• disableThumbnailScroll: Boolean, default false
• disableKeyDown: Boolean, default false
• disableSwipe: Boolean, default false
• disableThumbnailSwipe: Boolean, default false
• flickThreshold: Number, default 0.4 - swipe velocity threshold
• swipeThreshold: Number, default 30 - percentage of slide width needed to trigger navigation
• stopPropagation: Boolean, default false - call stopPropagation on swipe events
• useWindowKeyDown: Boolean, default true - use window or element for key events

Other

• lazyLoad: Boolean, default false
• startIndex: Number, default 0
• onErrorImageURL: String, default undefined - fallback image URL for failed loads
• indexSeparator: String, default ' / ' (ignored if showIndex is false)
• additionalClass: String, additional class for the root node

The GalleryItem interface defines the configuration for each individual image in the gallery. You can specify URLs for the original image, thumbnails, and fullscreen versions, as well as metadata like alt text, titles, and descriptions. It also supports custom rendering for the item itself or its thumbnail.

Key properties include:

• original: URL of the main image (required).
• thumbnail: URL of the thumbnail image.
• fullscreen: URL of the fullscreen image.
• description: Text shown below the image.
• renderItem: Custom function to render the item.
• renderThumbInner: Custom function to render the thumbnail inner content.

export interface GalleryItem {
  original: string;
  thumbnail?: string;
  fullscreen?: string;
  originalWidth?: string;
  originalHeight?: string;
  thumbnailWidth?: string | number;
  thumbnailHeight?: string | number;
  originalAlt?: string;
  thumbnailAlt?: string;
  originalTitle?: string;
  thumbnailTitle?: string;
  description?: string;
  thumbnailLabel?: string;
  originalClass?: string;
  thumbnailClass?: string;
  bulletClass?: string;
  loading?: "eager" | "lazy";
  thumbnailLoading?: "eager" | "lazy";
  srcSet?: string;
  sizes?: string;
  imageSet?: ImageSet[];
  renderItem?: (item: GalleryItem) => ReactNode;
  renderThumbInner?: (item: GalleryItem) => ReactNode;
  bulletOnClick?: (event: MouseEvent<HTMLButtonElement>, index: number) => void;
}

The ImageGalleryProps interface defines the configuration options for the main ImageGallery component. This includes settings for autoplay, navigation visibility, thumbnail positioning, and event callbacks.

Common configuration categories:

• Display Controls: showBullets, showFullscreenButton, showIndex, showNav, showPlayButton, showThumbnails.
• Behavior: autoPlay, infinite, isRTL, lazyLoad, slideVertically, startIndex.
• Navigation: thumbnailPosition ('top' | 'bottom' | 'left' | 'right'), slideDuration, slideInterval.
• Custom Rendering: renderItem, renderThumbInner, renderFullscreenButton, renderPlayPauseButton, etc.

export interface ImageGalleryProps {
  items: GalleryItem[];
  additionalClass?: string;
  autoPlay?: boolean;
  disableKeyDown?: boolean;
  disableSwipe?: boolean;
  disableThumbnailScroll?: boolean;
  disableThumbnailSwipe?: boolean;
  flickThreshold?: number;
  indexSeparator?: string;
  infinite?: boolean;
  isRTL?: boolean;
  lazyLoad?: boolean;
  onErrorImageURL?: string;
  showBullets?: boolean;
  maxBullets?: number;
  showFullscreenButton?: boolean;
  showIndex?: boolean;
  showNav?: boolean;
  showPlayButton?: boolean;
  showThumbnails?: boolean;
  slideDuration?: number;
  slideInterval?: number;
  slideOnThumbnailOver?: boolean;
  slideVertically?: boolean;
  startIndex?: number;
  stopPropagation?: boolean;
  swipeThreshold?: number;
  swipingTransitionDuration?: number;
  thumbnailPosition?: ThumbnailPosition;
  useBrowserFullscreen?: boolean;
  useTranslate3D?: boolean;
  useWindowKeyDown?: boolean;

  // Event Callbacks
  onBeforeSlide?: OnBeforeSlideCallback;
  onBulletClick?: OnBulletClickCallback;
  onClick?: OnClickCallback;
  onImageError?: OnImageErrorCallback;
  onImageLoad?: OnImageLoadCallback;
  onMouseLeave?: OnMouseCallback;
  onMouseOver?: OnMouseCallback;
  onPause?: OnPauseCallback;
  onPlay?: OnPlayCallback;
  onScreenChange?: OnScreenChangeCallback;
  onSlide?: OnSlideCallback;
  onThumbnailClick?: OnThumbnailClickCallback;
  onThumbnailError?: OnThumbnailErrorCallback;
  onTouchEnd?: OnTouchCallback;
  onTouchMove?: OnTouchCallback;
  onTouchStart?: OnTouchCallback;

  // Render Callbacks
  renderBottomNav?: RenderNavCallback;
  renderCustomControls?: RenderCustomControlsCallback;
  renderFullscreenButton?: RenderFullscreenCallback;
  renderItem?: RenderItemCallback;
  renderLeftNav?: RenderNavCallback;
  renderPlayPauseButton?: RenderPlayPauseCallback;
  renderRightNav?: RenderNavCallback;
  renderThumbInner?: RenderThumbInnerCallback;
  renderTopNav?: RenderNavCallback;
}