React Image Gallery
A responsive, customizable image gallery component for React
▶️ VIEW LIVE DEMO
✨ Features
| Feature | Description |
|---|
| 📱 Mobile Swipe | Native touch gestures for smooth mobile navigation |
| 🖼️ Thumbnails | Customizable thumbnail navigation with multiple positions |
| 📺 Fullscreen | Browser fullscreen or CSS-based fullscreen modes |
| 🎨 Theming | CSS custom properties for easy styling |
| ⌨️ Keyboard Nav | Arrow keys, escape, and custom key bindings |
| 🔄 RTL Support | Right-to-left language support |
| ↕️ Vertical Mode | Slide vertically instead of horizontally |
| 🎬 Custom Slides | Render videos, iframes, or any custom content |
🚀 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 URLthumbnail - thumbnail source URLfullscreen - 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 classthumbnailClass - custom thumbnail classrenderItem - Function for custom rendering a specific slide (see renderItem below)renderThumbInner - Function for custom thumbnail renderer (see renderThumbInner below)originalAlt - image altthumbnailAlt - thumbnail image altoriginalTitle - image titlethumbnailTitle - thumbnail image titlethumbnailLabel - label for thumbnaildescription - description for imagesrcSet - image srcset (html5 attribute)sizes - image sizes (html5 attribute)bulletClass - extra class for the bullet of the item
infinite: Boolean, default true - loop infinitelylazyLoad: Boolean, default falseshowNav: Boolean, default trueshowThumbnails: Boolean, default truethumbnailPosition: String, default bottom - options: top, right, bottom, leftshowFullscreenButton: Boolean, default trueuseBrowserFullscreen: Boolean, default true - if false, uses CSS-based fullscreenuseTranslate3D: Boolean, default true - if false, uses translate instead of translate3dshowPlayButton: Boolean, default trueisRTL: Boolean, default false - right-to-left modeshowBullets: Boolean, default falsemaxBullets: Number, default undefined - max bullets shown (minimum 3, active bullet stays centered)showIndex: Boolean, default falseautoPlay: Boolean, default falsedisableThumbnailScroll: Boolean, default false - disable thumbnail auto-scrolldisableKeyDown: Boolean, default false - disable keyboard navigationdisableSwipe: Boolean, default falsedisableThumbnailSwipe: Boolean, default falseonErrorImageURL: String, default undefined - fallback image URL for failed loadsindexSeparator: String, default ' / ', ignored if showIndex is falseslideDuration: Number, default 550 - slide transition duration (ms)swipingTransitionDuration: Number, default 0 - transition duration while swiping (ms)slideInterval: Number, default 3000slideOnThumbnailOver: Boolean, default falseslideVertically: Boolean, default false - slide vertically instead of horizontallyflickThreshold: Number, default 0.4 - swipe velocity threshold (lower = more sensitive)swipeThreshold: Number, default 30 - percentage of slide width needed to trigger navigationstopPropagation: Boolean, default false - call stopPropagation on swipe eventsstartIndex: Number, default 0onImageError: Function, callback(event) - overrides onErrorImageURLonThumbnailError: Function, callback(event) - overrides onErrorImageURLonThumbnailClick: 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 slideonTouchEnd: Function, callback(event) on gallery slideonTouchStart: Function, callback(event) on gallery slideonMouseOver: Function, callback(event) on gallery slideonMouseLeave: Function, callback(event) on gallery slideadditionalClass: String, additional class for the root noderenderCustomControls: Function, render custom controls on the current sliderenderItem: Function, custom slide renderingrenderThumbInner: Function, custom thumbnail renderingrenderLeftNav: Function, custom left nav componentrenderRightNav: Function, custom right nav componentrenderTopNav: Function, custom top nav component (vertical mode)renderBottomNav: Function, custom bottom nav component (vertical mode)renderPlayPauseButton: Function, custom play/pause buttonrenderFullscreenButton: Function, custom fullscreen buttonuseWindowKeyDown: Boolean, default true - use window or element for key events
🔧 Functions
The following functions can be accessed using refs
play(): starts the slideshowpause(): pauses the slideshowtogglePlay(): toggles between play and pausefullScreen(): enters fullscreen modeexitFullScreen(): exits fullscreen modetoggleFullScreen(): toggles fullscreen modeslideToIndex(index): slides to a specific indexgetCurrentIndex(): 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
