React carousel image gallery component with thumbnail and mobile support
npm install react-image-galleryA responsive, customizable image gallery component for React






ā¶ļø VIEW LIVE DEMO
| 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 |
```
npm install react-image-gallery
`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/",
},
];
function MyGallery() {
const galleryRef = useRef
return (
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 iteminfinite
- : 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
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