A responsive, customizable image gallery component for React
| 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 |
| Slide vertically instead of horizontally | |
| 🎬 Custom Slides | Render videos, iframes, or any custom content |
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
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, defaulttrue- loop infinitelylazyLoad: Boolean, defaultfalseshowNav: Boolean, defaulttrueshowThumbnails: Boolean, defaulttruethumbnailPosition: String, defaultbottom- options:top,right,bottom,leftshowFullscreenButton: Boolean, defaulttrueuseBrowserFullscreen: Boolean, defaulttrue- if false, uses CSS-based fullscreenuseTranslate3D: Boolean, defaulttrue- if false, usestranslateinstead oftranslate3dshowPlayButton: Boolean, defaulttrueisRTL: Boolean, defaultfalse- right-to-left modeshowBullets: Boolean, defaultfalsemaxBullets: Number, defaultundefined- max bullets shown (minimum 3, active bullet stays centered)showIndex: Boolean, defaultfalseautoPlay: Boolean, defaultfalsedisableThumbnailScroll: Boolean, defaultfalse- disable thumbnail auto-scrolldisableKeyDown: Boolean, defaultfalse- disable keyboard navigationdisableSwipe: Boolean, defaultfalsedisableThumbnailSwipe: Boolean, defaultfalseonErrorImageURL: String, defaultundefined- fallback image URL for failed loadsindexSeparator: String, default' / ', ignored ifshowIndexis falseslideDuration: Number, default550- slide transition duration (ms)swipingTransitionDuration: Number, default0- transition duration while swiping (ms)slideInterval: Number, default3000slideOnThumbnailOver: Boolean, defaultfalseslideVertically: Boolean, defaultfalse- slide vertically instead of horizontallyflickThreshold: Number, default0.4- swipe velocity threshold (lower = more sensitive)swipeThreshold: Number, default30- percentage of slide width needed to trigger navigationstopPropagation: Boolean, defaultfalse- call stopPropagation on swipe eventsstartIndex: Number, default0onImageError: Function,callback(event)- overridesonErrorImageURLonThumbnailError: Function,callback(event)- overridesonErrorImageURLonThumbnailClick: 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, defaulttrue- use window or element for key events
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
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
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.
MIT © Xiao Lin