React Image Gallery

https://github.com/xiaolin/react-image-gallery
Admin
React Image Gallery is a responsive, customizable image gallery component for React with thumbnail...
Tokens:11,894
Snippets:65
Trust Score:8.6
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Clone and Install React Image Gallery

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Instructions to clone the repository, install dependencies, and start the development server for the react-image-gallery example.

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

--------------------------------

### Install React Image Gallery

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Use npm to install the react-image-gallery package.

```bash
npm install react-image-gallery
```

--------------------------------

### Event Callbacks for Gallery Lifecycle

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Utilize various event callbacks to integrate analytics, lazy loading, or custom UX. This example logs events for slide changes, playback, fullscreen, image loading, and user interactions.

```tsx
import { useRef } from "react";
import ImageGallery from "react-image-gallery";
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/" },
];

export default function EventGallery() {
  const ref = useRef<ImageGalleryRef>(null);

  return (
    <ImageGallery
      ref={ref}
      items={images}
      // Slide lifecycle
      onBeforeSlide={(nextIndex) => console.log("Will slide to", nextIndex)}
      onSlide={(currentIndex) => console.log("Slid to", currentIndex)}
      // Play/pause
      onPlay={(index) => console.log("Playing from", index)}
      onPause={(index) => console.log("Paused at", index)}
      // Fullscreen
      onScreenChange={(isFullscreen) => console.log("Fullscreen:", isFullscreen)}
      // Image load/error
      onImageLoad={(e) => console.log("Image loaded:", (e.target as HTMLImageElement).src)}
      onImageError={(e) => console.warn("Image failed:", (e.target as HTMLImageElement).src)}
      onErrorImageURL="https://via.placeholder.com/1000x600?text=Error"
      onThumbnailError={(e) => console.warn("Thumbnail error")}
      // Interaction
      onClick={(e) => console.log("Slide clicked, current index:", ref.current?.getCurrentIndex())}
      onThumbnailClick={(e, index) => console.log("Thumbnail clicked:", index)}
      onBulletClick={(e, index) => console.log("Bullet clicked:", index)}
      // Mouse
      onMouseOver={(e) => console.log("Mouse over gallery")}
      onMouseLeave={(e) => console.log("Mouse left gallery")}
    />
  );
}
```

--------------------------------

### Basic React Image Gallery Implementation

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Import the ImageGallery component and its CSS. Define an array of image objects, each with 'original' and 'thumbnail' URLs. Use the useRef hook to get a reference to the gallery instance for potential programmatic control. Pass the image data to the 'items' prop and optionally handle slide events.

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

--------------------------------

### Render Custom Controls in React Image Gallery

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Use the `renderCustomControls` prop to add custom UI elements like a download button directly into the slide wrapper. This example shows how to open the current image in a new tab when the button is clicked.

```tsx
import { useRef } from "react";
import ImageGallery from "react-image-gallery";
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/" },
];

export default function CustomControlsGallery() {
  const ref = useRef<ImageGalleryRef>(null);

  return (
    <ImageGallery
      ref={ref}
      items={images}
      renderCustomControls={() => (
        <button
          style={{
            position: "absolute",
            top: 8,
            left: 8,
            zIndex: 4,
            background: "rgba(0,0,0,.6)",
            color: "#fff",
            border: "none",
            borderRadius: 4,
            padding: "4px 8px",
            cursor: "pointer",
          }}
          onClick={() => {
            const url = images[ref.current?.getCurrentIndex() ?? 0].original;
            window.open(url, "_blank");
          }}
        >
          ⬇ Download
        </button>
      )}
    />
  );
}
```

--------------------------------

### Custom Thumbnail Rendering with `renderThumbInner`

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Replace default thumbnails with custom content, such as an image overlaid with a label. This example shows how to render an image with a text label at the bottom.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
    thumbnailLabel: "Mountains",
    description: "A scenic mountain range",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
    thumbnailLabel: "Forest",
  },
];

export default function CustomThumbGallery() {
  return (
    <ImageGallery
      items={images}
      renderThumbInner={(item) => (
        <div style={{ position: "relative", overflow: "hidden" }}>
          <img
            src={item.thumbnail}
            alt={item.thumbnailAlt ?? item.thumbnailLabel}
            style={{ width: "100%", display: "block" }}
          />
          {item.thumbnailLabel && (
            <div
              style={{
                position: "absolute",
                bottom: 0,
                left: 0,
                right: 0,
                background: "rgba(0,0,0,.6)",
                color: "#fff",
                fontSize: 10,
                padding: "2px 4px",
                textAlign: "center",
              }}
            >
              {item.thumbnailLabel}
            </div>
          )}
        </div>
      )}
    />
  );
}
```

--------------------------------

### Custom Slide Rendering with Videos in React Image Gallery

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Override individual slide rendering using `renderItem` for embedding videos or iframes. This example shows how to conditionally render a video player or a thumbnail with a play button.

```tsx
import { useState } from "react";
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

interface VideoItem extends GalleryItem {
  embedUrl?: string;
}

function VideoSlide({ item, onClose }: { item: VideoItem; onClose: () => void }) {
  return (
    <div style={{ position: "relative", textAlign: "center" }}>
      <button onClick={onClose} style={{ position: "absolute", top: 8, right: 8, zIndex: 5 }}>
        ✕ Close
      </button>
      <iframe
        allowFullScreen
        src={item.embedUrl}
        width="560"
        height="315"
        style={{ border: "none" }}
        title="Video"
      />
    </div>
  );
}

export default function VideoGallery() {
  const [showVideo, setShowVideo] = useState(false);

  const items: VideoItem[] = [
    {
      original: "https://picsum.photos/id/1018/1000/600/",
      thumbnail: "https://picsum.photos/id/1018/250/150/",
      embedUrl: "https://www.youtube.com/embed/4pSzhZ76GdM?autoplay=1&showinfo=0",
      description: "Click play to watch video",
      renderItem: (item) =>
        showVideo ? (
          <VideoSlide item={item as VideoItem} onClose={() => setShowVideo(false)} />
        ) : (
          <div style={{ position: "relative" }}>
            <button onClick={() => setShowVideo(true)} style={{ position: "absolute", inset: 0, zIndex: 3, background: "rgba(0,0,0,.5)", color: "#fff", border: "none", cursor: "pointer", fontSize: 48 }}>
              ▶
            </button>
            <img className="image-gallery-image" src={item.original} alt="Video thumbnail" />
          </div>
        ),
    },
    {
      original: "https://picsum.photos/id/1015/1000/600/",
      thumbnail: "https://picsum.photos/id/1015/250/150/",
    },
  ];

  return <ImageGallery items={items} onSlide={() => setShowVideo(false)} />;
}
```

--------------------------------

### Basic Image Gallery Usage

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Demonstrates the basic usage of the ImageGallery component with a required 'items' prop. Each item needs an 'original' URL and preferably a 'thumbnail' URL.

```tsx
import ImageGallery from "react-image-gallery";
import "react-image-gallery/styles/image-gallery.css";
import type { GalleryItem } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
    originalAlt: "Mountain landscape",
    thumbnailAlt: "Mountain landscape thumbnail",
    description: "Beautiful mountain view",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
    description: "Forest path",
  },
  {
    original: "https://picsum.photos/id/1019/1000/600/",
    thumbnail: "https://picsum.photos/id/1019/250/150/",
  },
];

export default function BasicGallery() {
  return <ImageGallery items={images} />;
}
```

--------------------------------

### Programmatic Control with `ref`

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Access imperative methods like play, pause, togglePlay, fullScreen, exitFullScreen, toggleFullScreen, slideToIndex, and getCurrentIndex by attaching a ref typed as ImageGalleryRef.

```APIDOC
## `ref` API — Programmatic control

Attach a ref typed as `ImageGalleryRef` to access imperative methods: `play`, `pause`, `togglePlay`, `fullScreen`, `exitFullScreen`, `toggleFullScreen`, `slideToIndex`, and `getCurrentIndex`.

```tsx
import { useRef } from "react";
import ImageGallery from "react-image-gallery";
import type { ImageGalleryRef, GalleryItem } 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/" },
];

export default function ControlledGallery() {
  const galleryRef = useRef<ImageGalleryRef>(null);

  return (
    <div>
      <ImageGallery ref={galleryRef} items={images} showPlayButton={false} />
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={() => galleryRef.current?.play()}>▶ Play</button>
        <button onClick={() => galleryRef.current?.pause()}>⏸ Pause</button>
        <button onClick={() => galleryRef.current?.togglePlay()}>⏯ Toggle</button>
        <button onClick={() => galleryRef.current?.slideToIndex(0)}>Go to #1</button>
        <button onClick={() => galleryRef.current?.fullScreen()}>⛶ Fullscreen</button>
        <button onClick={() => galleryRef.current?.exitFullScreen()}>✕ Exit FS</button>
        <button onClick={() => alert(`Current: ${galleryRef.current?.getCurrentIndex()}`)}>
          Current Index
        </button>
      </div>
    </div>
  );
}
```
```

--------------------------------

### Autoplay and Slideshow Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Configure autoplay behavior and transition timing using props such as autoPlay, slideInterval, and slideDuration. This section also covers infinite looping and the visibility of the play/pause button.

```APIDOC
## Autoplay and slideshow configuration

Control autoplay behavior and transition timing with `autoPlay`, `slideInterval`, `slideDuration`, and related props.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function AutoPlayGallery() {
  return (
    <ImageGallery
      items={images}
      autoPlay={true}           // Start slideshow on mount
      slideInterval={3000}      // 3 seconds between slides
      slideDuration={550}       // 550ms transition animation
      infinite={true}           // Loop back to start
      showPlayButton={true}     // Show the play/pause button
      onPlay={(index) => console.log("Autoplay started at index", index)}
      onPause={(index) => console.log("Autoplay paused at index", index)}
    />
  );
}
```
```

--------------------------------

### GalleryItem Configuration Options

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Details the extensive configuration options available for each item in the 'items' array, including responsive images, lazy loading, and custom classes.

```tsx
import type { GalleryItem, ImageSet } from "react-image-gallery";

const advancedItems: GalleryItem[] = [
  {
    // Required
    original: "https://example.com/photo-large.jpg",
    // Thumbnail
    thumbnail: "https://example.com/photo-thumb.jpg",
    thumbnailLabel: "Photo 1",
    thumbnailLoading: "lazy",
    thumbnailWidth: 120,
    thumbnailHeight: 80,
    // Fullscreen-specific image (higher res)
    fullscreen: "https://example.com/photo-fullres.jpg",
    // Alt & title
    originalAlt: "A scenic photo",
    thumbnailAlt: "Thumbnail of scenic photo",
    originalTitle: "Scenic",
    thumbnailTitle: "Scenic thumb",
    // Description overlay
    description: "Caption shown below the image",
    // Dimensions (hint for layout)
    originalWidth: "1000",
    originalHeight: "600",
    // Responsive srcset
    srcSet: "photo-sm.jpg 480w, photo-md.jpg 800w, photo-large.jpg 1200w",
    sizes: "(max-width: 768px) 100vw, 800px",
    // Responsive <picture> image sets
    imageSet: [
      { srcSet: "photo-webp.webp", media: "(min-width: 768px)" },
    ] as ImageSet[],
    // Loading strategy
    loading: "lazy",
    // Custom CSS classes
    originalClass: "featured-slide",
    thumbnailClass: "featured-thumb",
    bulletClass: "featured-bullet",
  },
];
```

--------------------------------

### Enable Right-to-Left (RTL) Support

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Activate RTL layout for languages like Arabic and Hebrew by setting `isRTL={true}`. Ensure the parent container has `dir="rtl"` for correct text and layout direction.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

const images: GalleryItem[] = [
  { original: "https://picsum.photos/id/1018/1000/600/", thumbnail: "https://picsum.photos/id/1018/250/150/", description: "صورة جميلة" },
  { original: "https://picsum.photos/id/1015/1000/600/", thumbnail: "https://picsum.photos/id/1015/250/150/" },
];

export default function RTLGallery() {
  return (
    <div dir="rtl">
      <ImageGallery items={images} isRTL={true} />
    </div>
  );
}
```

--------------------------------

### Autoplay and Slideshow Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Configure the slideshow behavior using props like `autoPlay`, `slideInterval`, and `slideDuration`. Event handlers `onPlay` and `onPause` can be used to track state changes.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function AutoPlayGallery() {
  return (
    <ImageGallery
      items={images}
      autoPlay={true}           // Start slideshow on mount
      slideInterval={3000}      // 3 seconds between slides
      slideDuration={550}       // 550ms transition animation
      infinite={true}           // Loop back to start
      showPlayButton={true}     // Show the play/pause button
      onPlay={(index) => console.log("Autoplay started at index", index)}
      onPause={(index) => console.log("Autoplay paused at index", index)}
    />
  );
}
```

--------------------------------

### Programmatic Control with `ref` API

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Attach a ref to the ImageGallery component to access imperative methods for controlling playback, fullscreen, and slide navigation. Ensure the ref is typed as ImageGalleryRef.

```tsx
import { useRef } from "react";
import ImageGallery from "react-image-gallery";
import type { ImageGalleryRef, GalleryItem } 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/" },
];

export default function ControlledGallery() {
  const galleryRef = useRef<ImageGalleryRef>(null);

  return (
    <div>
      <ImageGallery ref={galleryRef} items={images} showPlayButton={false} />
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={() => galleryRef.current?.play()}>▶ Play</button>
        <button onClick={() => galleryRef.current?.pause()}>⏸ Pause</button>
        <button onClick={() => galleryRef.current?.togglePlay()}>⏯ Toggle</button>
        <button onClick={() => galleryRef.current?.slideToIndex(0)}>Go to #1</button>
        <button onClick={() => galleryRef.current?.fullScreen()}>⛶ Fullscreen</button>
        <button onClick={() => galleryRef.current?.exitFullScreen()}>✕ Exit FS</button>
        <button onClick={() => alert(`Current: ${galleryRef.current?.getCurrentIndex()}`)}>
          Current Index
        </button>
      </div>
    </div>
  );
}
```

--------------------------------

### Navigation Functions

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Functions for navigating through the gallery images.

```APIDOC
## slideToIndex(index)

### Description
Slides the gallery to display the image at the specified index.

### Method
`slideToIndex(index)`

### Parameters
#### Path Parameters
- **index** (number) - Required - The index of the image to slide to.
```

```APIDOC
## getCurrentIndex()

### Description
Returns the index of the currently displayed image.

### Method
`getCurrentIndex()`

### Parameters
None

### Response
#### Success Response (200)
- **currentIndex** (number) - The index of the current image.
```

--------------------------------

### Thumbnail Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Customize the appearance and behavior of thumbnails, including their position, visibility, scroll behavior, and swipe interactions, using props like thumbnailPosition, showThumbnails, and disableThumbnailSwipe.

```APIDOC
## Thumbnail configuration

Control thumbnail position, visibility, scroll behavior, and swipe with `thumbnailPosition`, `showThumbnails`, `disableThumbnailScroll`, `disableThumbnailSwipe`, and `slideOnThumbnailOver`.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem, ThumbnailPosition } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
    thumbnailLabel: "Mountains",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
    thumbnailLabel: "Forest",
  },
];

// thumbnailPosition options: "top" | "bottom" | "left" | "right"
const position: ThumbnailPosition = "left";

export default function ThumbnailGallery() {
  return (
    <ImageGallery
      items={images}
      thumbnailPosition={position}          // Thumbnail strip on the left
      showThumbnails={true}
      disableThumbnailScroll={false}        // Auto-scroll thumbnails to active
      disableThumbnailSwipe={false}         // Allow swiping the thumbnail strip
      slideOnThumbnailOver={true}           // Slide on thumbnail hover
      onThumbnailClick={(event, index) =>
        console.log("Thumbnail clicked:", index)
      }
    />
  );
}
```
```

--------------------------------

### Fullscreen Control Functions

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Functions to manage the fullscreen mode of the gallery.

```APIDOC
## fullScreen()

### Description
Enters fullscreen mode for the image gallery.

### Method
`fullScreen()`

### Parameters
None

### Response
None
```

```APIDOC
## exitFullScreen()

### Description
Exits fullscreen mode for the image gallery.

### Method
`exitFullScreen()`

### Parameters
None

### Response
None
```

```APIDOC
## toggleFullScreen()

### Description
Toggles between fullscreen and normal mode for the image gallery.

### Method
`toggleFullScreen()`

### Parameters
None

### Response
None
```

--------------------------------

### Configure Fullscreen Mode in React Image Gallery

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Use `showFullscreenButton`, `useBrowserFullscreen`, and `onScreenChange` to control fullscreen behavior. `renderFullscreenButton` allows for a custom button.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function FullscreenGallery() {
  return (
    <ImageGallery
      items={images}
      showFullscreenButton={true}
      useBrowserFullscreen={true}         // false = CSS modal fullscreen
      onScreenChange={(isFullscreen) =>
        console.log("Fullscreen state:", isFullscreen)
      }
      // Custom fullscreen button
      renderFullscreenButton={(onClick, isFullscreen) => (
        <button
          className="custom-fullscreen-btn"
          onClick={onClick}
          style={{ position: "absolute", bottom: 8, right: 8, zIndex: 4 }}
        >
          {isFullscreen ? "Exit Fullscreen" : "Fullscreen"}
        </button>
      )}
    />
  );
}
```

--------------------------------

### Image Gallery Props

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Configuration options for the React Image Gallery component.

```APIDOC
## Image Gallery Props

### `items` (required)
Array of objects. Each object represents an image 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`: Thumbnail height (HTML5 attribute).
- `thumbnailWidth`: Thumbnail width (HTML5 attribute).
- `thumbnailLoading`: 'lazy' or 'eager' (HTML5 attribute).
- `originalClass`: Custom class for the original image.
- `thumbnailClass`: Custom class for the thumbnail.
- `renderItem`: Function for custom rendering of a slide.
- `renderThumbInner`: Function for custom rendering of a thumbnail.
- `originalAlt`: Alt text for the original image.
- `thumbnailAlt`: Alt text for the thumbnail.
- `originalTitle`: Title attribute for the original image.
- `thumbnailTitle`: Title attribute for the thumbnail.
- `thumbnailLabel`: Label for the thumbnail.
- `description`: Description for the image.
- `srcSet`: Image srcset (HTML5 attribute).
- `sizes`: Image sizes (HTML5 attribute).
- `bulletClass`: Extra class for the item's bullet.

### `infinite`
Boolean, default `true`. Enables infinite looping of the gallery.

### `lazyLoad`
Boolean, default `false`. Enables lazy loading of images.

### `showNav`
Boolean, default `true`. Shows or hides the navigation arrows.

### `showThumbnails`
Boolean, default `true`. Shows or hides the thumbnails.

### `thumbnailPosition`
String, default `bottom`. Position of the thumbnails. Options: `top`, `right`, `bottom`, `left`.

### `showFullscreenButton`
Boolean, default `true`. Shows or hides the fullscreen button.

### `useBrowserFullscreen`
Boolean, default `true`. If `false`, uses CSS-based fullscreen.

### `useTranslate3D`
Boolean, default `true`. If `false`, uses `translate` instead of `translate3d` for animations.

### `showPlayButton`
Boolean, default `true`. Shows or hides the play/pause button.

### `isRTL`
Boolean, default `false`. Enables right-to-left mode.

### `showBullets`
Boolean, default `false`. Shows or hides the bullet navigation.

### `maxBullets`
Number, default `undefined`. Maximum number of bullets shown (minimum 3, active bullet stays centered).

### `showIndex`
Boolean, default `false`. Shows the current slide index.

### `autoPlay`
Boolean, default `false`. Enables automatic playback of slides.

### `disableThumbnailScroll`
Boolean, default `false`. Disables auto-scrolling of thumbnails.

### `disableKeyDown`
Boolean, default `false`. Disables keyboard navigation.

### `disableSwipe`
Boolean, default `false`. Disables swiping gestures on the gallery.

### `disableThumbnailSwipe`
Boolean, default `false`. Disables swiping gestures on the thumbnails.

### `onErrorImageURL`
String, default `undefined`. Fallback image URL for failed loads.

### `indexSeparator`
String, default `' / '`. Separator for the index display (ignored if `showIndex` is false).

### `slideDuration`
Number, default `550`. Duration of slide transitions in milliseconds.

### `swipingTransitionDuration`
Number, default `0`. Transition duration while swiping in milliseconds.

### `slideInterval`
Number, default `3000`. Interval between automatic slide changes in milliseconds.

### `slideOnThumbnailOver`
Boolean, default `false`. Triggers slide change when hovering over thumbnails.

### `slideVertically`
Boolean, default `false`. Enables vertical sliding instead of horizontal.

### `flickThreshold`
Number, default `0.4`. Swipe velocity threshold (lower values make it more sensitive).

### `swipeThreshold`
Number, default `30`. Percentage of slide width needed to trigger navigation.

### `stopPropagation`
Boolean, default `false`. Calls `stopPropagation` on swipe events.

### `startIndex`
Number, default `0`. The index of the initially displayed slide.

### `onImageError`
Function, `callback(event)`. Overrides `onErrorImageURL`.

### `onThumbnailError`
Function, `callback(event)`. Overrides `onErrorImageURL`.

### `onThumbnailClick`
Function, `callback(event, index)`. Callback when a thumbnail is clicked.

### `onBulletClick`
Function, `callback(event, index)`. Callback when a bullet is clicked.

### `onImageLoad`
Function, `callback(event)`. Callback when an image finishes loading.

### `onSlide`
Function, `callback(currentIndex)`. Callback when a slide changes.

### `onBeforeSlide`
Function, `callback(nextIndex)`. Callback before a slide changes.

### `onScreenChange`
Function, `callback(isFullscreen)`. Callback when the fullscreen state changes.

### `onPause`
Function, `callback(currentIndex)`. Callback when playback is paused.

### `onPlay`
Function, `callback(currentIndex)`. Callback when playback starts.

### `onClick`
Function, `callback(event)`. Callback when the gallery is clicked.

### `onTouchMove`
Function, `callback(event)`. Callback on gallery slide touch move.

### `onTouchEnd`
Function, `callback(event)`. Callback on gallery slide touch end.

### `onTouchStart`
Function, `callback(event)`. Callback on gallery slide touch start.

### `onMouseOver`
Function, `callback(event)`. Callback on gallery slide mouse over.

### `onMouseLeave`
Function, `callback(event)`. Callback on gallery slide mouse leave.

### `additionalClass`
String. Additional class for the root node of the gallery.

### `renderCustomControls`
Function. Renders custom controls on the current slide.

### `renderItem`
Function. Custom slide rendering function.

### `renderThumbInner`
Function. Custom thumbnail rendering function.

### `renderLeftNav`
Function. Custom component for the left navigation.

### `renderRightNav`
Function. Custom component for the right navigation.

### `renderTopNav`
Function. Custom component for the top navigation (in vertical mode).

### `renderBottomNav`
Function. Custom component for the bottom navigation (in vertical mode).

### `renderPlayPauseButton`
Function. Custom component for the play/pause button.

### `renderFullscreenButton`
Function. Custom component for the fullscreen button.

### `useWindowKeyDown`
Boolean, default `true`. Determines if key events are listened on the window or the gallery element.
```

--------------------------------

### Bullet and Index Indicator Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Enable dot bullet navigation with `showBullets` and a slide counter with `showIndex`. Use `maxBullets` to limit visible bullets and `indexSeparator` to customize the counter's separator.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

const images: GalleryItem[] = Array.from({ length: 10 }, (_, i) => ({
  original: `https://picsum.photos/id/${1010 + i}/1000/600/`,
  thumbnail: `https://picsum.photos/id/${1010 + i}/250/150/`,
  bulletClass: i === 0 ? "featured-bullet" : undefined,
}));

export default function BulletGallery() {
  return (
    <ImageGallery
      items={images}
      showBullets={true}
      maxBullets={5}               // Show at most 5 bullets; active stays centered
      showIndex={true}             // Show "3 / 10" counter
      indexSeparator=" of "        // Custom separator: "3 of 10"
      showThumbnails={false}
      onBulletClick={(event, index) => console.log("Bullet clicked:", index)}
    />
  );
}
```

--------------------------------

### Customize Gallery Appearance with CSS Variables

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Modify the gallery's design tokens using CSS custom properties. Define these properties on `:root` for global changes or on a specific parent element (e.g., `.my-dark-gallery`) for scoped theming. This allows customization of colors, sizes, and borders.

```css
/* globals.css — override the gallery's design tokens */
:root {
  --ig-primary-color: #e91e63;       /* Accent color for hover & active states */
  --ig-white: #ffffff;               /* Icon and text color */
  --ig-black: #111111;               /* Fullscreen background */
  --ig-background-overlay: rgba(0, 0, 0, 0.6); /* Description overlay */
  --ig-thumbnail-size: 80px;         /* Thumbnail width/height */
  --ig-thumbnail-size-small: 64px;   /* Thumbnail size on mobile */
  --ig-thumbnail-border-width: 3px;  /* Active thumbnail border */
  --ig-bullet-size: 6px;             /* Bullet dot size */
  --ig-bullet-size-small: 4px;       /* Bullet size on mobile */
}

/* Scoped theming — only affects this gallery instance */
.my-dark-gallery {
  --ig-primary-color: #90caf9;
  --ig-background-overlay: rgba(255, 255, 255, 0.1);
}
```

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

const images: GalleryItem[] = [
  { original: "https://picsum.photos/id/1018/1000/600/", thumbnail: "https://picsum.photos/id/1018/250/150/" },
];

export default function ThemedGallery() {
  return (
    // additionalClass applies to the root .image-gallery element
    <ImageGallery items={images} additionalClass="my-dark-gallery" />
  );
}
```

--------------------------------

### Enable Lazy Loading for Large Image Collections

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Use `lazyLoad={true}` to defer loading of off-screen images until they are close to the current slide. This improves performance for large galleries. Set `loading="lazy"` and `thumbnailLoading="lazy"` on individual items for per-item HTML loading attribute.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } from "react-image-gallery";

// Large collection — only load images near the current slide
const images: GalleryItem[] = Array.from({ length: 50 }, (_, i) => ({
  original: `https://picsum.photos/id/${1000 + i}/1000/600/`,
  thumbnail: `https://picsum.photos/id/${1000 + i}/250/150/`,
  loading: "lazy",          // Per-item HTML loading attribute
  thumbnailLoading: "lazy",
}));

export default function LazyGallery() {
  return (
    <ImageGallery
      items={images}
      lazyLoad={true}         // Only render slides adjacent to the current one
      infinite={false}        // Optional: disable infinite loop for large sets
      startIndex={0}
      onErrorImageURL="https://via.placeholder.com/1000x600?text=Image+Not+Found"
    />
  );
}
```

--------------------------------

### Swipe and Touch Gesture Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Fine-tune mobile swipe behavior using `swipeThreshold`, `flickThreshold`, `swipingTransitionDuration`, `disableSwipe`, and `stopPropagation`. Event handlers for touch gestures are also available.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function SwipeGallery() {
  return (
    <ImageGallery
      items={images}
      disableSwipe={false}
      swipeThreshold={30}              // 30% of slide width to trigger navigation
      flickThreshold={0.4}             // Velocity threshold for flick detection (0–1)
      swipingTransitionDuration={0}    // Transition duration during active swipe (ms)
      stopPropagation={false}          // Set true if gallery is inside a scrollable container
      disableThumbnailSwipe={false}
      onTouchStart={(e) => console.log("Touch started")}
      onTouchMove={(e) => console.log("Touching")}
      onTouchEnd={(e) => console.log("Touch ended")}
    />
  );
}
```

--------------------------------

### Thumbnail Configuration

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Customize the appearance and behavior of thumbnails using props such as `thumbnailPosition`, `showThumbnails`, `disableThumbnailScroll`, and `disableThumbnailSwipe`. Event handlers like `onThumbnailClick` are available.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem, ThumbnailPosition } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
    thumbnailLabel: "Mountains",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
    thumbnailLabel: "Forest",
  },
];

// thumbnailPosition options: "top" | "bottom" | "left" | "right"
const position: ThumbnailPosition = "left";

export default function ThumbnailGallery() {
  return (
    <ImageGallery
      items={images}
      thumbnailPosition={position}          // Thumbnail strip on the left
      showThumbnails={true}
      disableThumbnailScroll={false}        // Auto-scroll thumbnails to active
      disableThumbnailSwipe={false}         // Allow swiping the thumbnail strip
      slideOnThumbnailOver={true}           // Slide on thumbnail hover
      onThumbnailClick={(event, index) =>
        console.log("Thumbnail clicked:", index)
      }
    />
  );
}
```

--------------------------------

### Implement Vertical Sliding Mode

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Switch the sliding direction to vertical using `slideVertically={true}`. Navigation arrows will appear at the top and bottom. Consider using `thumbnailPosition="right"` for better usability with vertical slides.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function VerticalGallery() {
  return (
    <ImageGallery
      items={images}
      slideVertically={true}
      thumbnailPosition="right"   // Side thumbnails work best with vertical slides
      showBullets={false}
    />
  );
}
```

--------------------------------

### Slideshow Control Functions

Source: https://github.com/xiaolin/react-image-gallery/blob/master/README.md

Functions to control the automatic slideshow playback.

```APIDOC
## play()

### Description
Starts the slideshow playback.

### Method
`play()`

### Parameters
None

### Response
None
```

```APIDOC
## pause()

### Description
Pauses the slideshow playback.

### Method
`pause()`

### Parameters
None

### Response
None
```

```APIDOC
## togglePlay()

### Description
Toggles between playing and pausing the slideshow.

### Method
`togglePlay()`

### Parameters
None

### Response
None
```

--------------------------------

### Custom Navigation Controls with React Elements

Source: https://context7.com/xiaolin/react-image-gallery/llms.txt

Replace default navigation arrows with custom React buttons. Ensure to pass onClick and disabled props to your custom elements.

```tsx
import ImageGallery from "react-image-gallery";
import type { GalleryItem } 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/" },
];

export default function CustomNavGallery() {
  return (
    <ImageGallery
      items={images}
      renderLeftNav={(onClick, disabled) => (
        <button
          disabled={disabled}
          onClick={onClick}
          style={{
            position: "absolute", left: 8, top: "50%", transform: "translateY(-50%)",
            zIndex: 4, background: "#337ab7", color: "#fff", border: "none",
            borderRadius: 4, padding: "8px 12px", cursor: disabled ? "not-allowed" : "pointer",
            opacity: disabled ? 0.4 : 1,
          }}
        >
          ← Prev
        </button>
      )}
      renderRightNav={(onClick, disabled) => (
        <button
          disabled={disabled}
          onClick={onClick}
          style={{
            position: "absolute", right: 8, top: "50%", transform: "translateY(-50%)",
            zIndex: 4, background: "#337ab7", color: "#fff", border: "none",
            borderRadius: 4, padding: "8px 12px", cursor: disabled ? "not-allowed" : "pointer",
            opacity: disabled ? 0.4 : 1,
          }}
        >
          Next →
        </button>
      )}
    />
  );
}
```
Tokens:
Raw