Nybble Processing Mainframe

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/react-image-gallery package

    1.2.9 • Public • Published

    React Image Gallery

    npm version Download Count Bundle size

    Live Demo (try it on mobile for swipe support)


    demo gif

    React image gallery is a React component for building image galleries and carousels


    • Mobile swipe gestures
    • Thumbnail navigation
    • Fullscreen support
    • Custom rendered slides
    • RTL support
    • Responsive design
    • Tons of customization options (see props below)

    Getting started

    React Image Gallery requires React 16.0.0 or later.

    npm install react-image-gallery

    Style import (with webpack)

    # SCSS
    @import "~react-image-gallery/styles/scss/image-gallery.scss";
    # CSS
    @import "~react-image-gallery/styles/css/image-gallery.css";


    Need more example? See example/app.js

    import ImageGallery from 'react-image-gallery';
    const images = [
        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/',
    class MyGallery extends React.Component {
      render() {
        return <ImageGallery items={images} />;


    • items: (required) Array of objects, see example above,

      • Available Properties
        • original - image src url
        • thumbnail - image thumbnail src url
        • fullscreen - image for fullscreen (defaults to original)
        • originalHeight - image height (html5 attribute)
        • originalWidth - image width (html5 attribute)
        • loading - image loading. Either "lazy" or "eager" (html5 attribute)
        • thumbnailHeight - image height (html5 attribute)
        • thumbnailWidth - image width (html5 attribute)
        • thumbnailLoading - image loading. Either "lazy" or "eager" (html5 attribute)
        • originalClass - custom image class
        • thumbnailClass - custom thumbnail class
        • renderItem - Function for custom rendering a specific slide (see renderItem below)
        • renderThumbInner - Function for custom thumbnail renderer (see renderThumbInner below)
        • 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
        • bulletOnClick - callback({item, itemIndex, currentIndex})
          • A function that will be called upon bullet click.
    • infinite: Boolean, default true

      • infinite sliding
    • lazyLoad: Boolean, default false

    • showNav: Boolean, default true

    • showThumbnails: Boolean, default true

    • thumbnailPosition: String, default bottom

      • available positions: top, right, bottom, left
    • showFullscreenButton: Boolean, default true

    • useBrowserFullscreen: Boolean, default true

      • if false, fullscreen will be done via css within the browser
    • useTranslate3D: Boolean, default true

      • if false, will use translate instead of translate3d css property to transition slides
    • showPlayButton: Boolean, default true

    • isRTL: Boolean, default false

      • if true, gallery's direction will be from right-to-left (to support right-to-left languages)
    • showBullets: Boolean, default false

    • showIndex: Boolean, default false

    • autoPlay: Boolean, default false

    • disableThumbnailScroll: Boolean, default false

      • disables the thumbnail container from adjusting
    • disableKeyDown: Boolean, default false

      • disables keydown listener for keyboard shortcuts (left arrow, right arrow, esc key)
    • disableSwipe: Boolean, default false

    • disableThumbnailSwipe: Boolean, default false

    • onErrorImageURL: String, default undefined

      • an image src pointing to your default image if an image fails to load
      • handles both slide image, and thumbnail image
    • indexSeparator: String, default ' / ', ignored if showIndex is false

    • slideDuration: Number, default 450

      • transition duration during image slide in milliseconds
    • swipingTransitionDuration: Number, default 0

      • transition duration while swiping in milliseconds
    • slideInterval: Number, default 3000

    • slideOnThumbnailOver: Boolean, default false

    • flickThreshold: Number (float), default 0.4

      • Determines the max velocity of a swipe before it's considered a flick (lower = more sensitive)
    • swipeThreshold: Number, default 30

      • A percentage of how far the offset of the current slide is swiped to trigger a slide event. e.g. If the current slide is swiped less than 30% to the left or right, it will not trigger a slide event.
    • stopPropagation: Boolean, default false

      • Automatically calls stopPropagation on all 'swipe' events.
    • startIndex: Number, default 0

    • onImageError: Function, callback(event)

      • overrides onErrorImage
    • onThumbnailError: Function, callback(event)

      • overrides onErrorImage
    • onThumbnailClick: Function, callback(event, index)

    • onImageLoad: Function, callback(event)

    • onSlide: Function, callback(currentIndex)

    • onBeforeSlide: Function, callback(nextIndex)

    • onScreenChange: Function, callback(boolean)

      • When fullscreen is toggled a boolean is passed to the callback
    • onPause: Function, callback(currentIndex)

    • onPlay: Function, callback(currentIndex)

    • onClick: Function, callback(event)

    • onTouchMove: Function, callback(event) on gallery slide

    • onTouchEnd: Function, callback(event) on gallery slide

    • onTouchStart: Function, callback(event) on gallery slide

    • onMouseOver: Function, callback(event) on gallery slide

    • onMouseLeave: Function, callback(event) on gallery slide

    • additionalClass: String,

      • Additional class that will be added to the root node of the component.
    • renderCustomControls: Function, custom controls rendering

      • Use this to render custom controls or other elements on the currently displayed image (like the fullscreen button)
        _renderCustomControls() {
          return <a href='' className='image-gallery-custom-action' onClick={this._customAction.bind(this)}/>
    • renderItem: Function, custom item rendering

      • NOTE: Highly suggest looking into a render cache such as React.memo if you plan to override renderItem
      • On a specific item [{thumbnail: '...', renderItem: this.myRenderItem}]
      • As a prop passed into ImageGallery to completely override renderItem, see source for renderItem implementation
    • renderThumbInner: Function, custom thumbnail rendering

      • On a specific item [{thumbnail: '...', renderThumbInner: this.myRenderThumbInner}]
      • As a prop passed into ImageGallery to completely override _renderThumbInner, see source for reference
    • renderLeftNav: Function, custom left nav component

      • See <LeftNav />
      • Use this to render a custom left nav control
      • Args:
        • onClick callback that will slide to the previous item
        • disabled boolean for when the nav is disabled
        renderLeftNav: (onClick, disabled) => (
          <LeftNav onClick={onClick} disabled={disabled} />
    • renderRightNav: Function, custom right nav component

      • See <RightNav />
      • Use this to render a custom right nav control
      • Args:
        • onClick callback that will slide to the next item
        • disabled boolean for when the nav is disabled
        renderRightNav: (onClick, disabled) => (
          <RightNav onClick={onClick} disabled={disabled} />
    • renderPlayPauseButton: Function, play pause button component

      • See <PlayPause />
      • Use this to render a custom play pause button
      • Args:
        • onClick callback that will toggle play/pause
        • isPlaying boolean for when gallery is playing
        renderPlayPauseButton: (onClick, isPlaying) => (
          <PlayPause onClick={onClick} isPlaying={isPlaying} />
    • renderFullscreenButton: Function, custom fullscreen button component

      • See <Fullscreen />
      • Use this to render a custom fullscreen button
      • Args:
        • onClick callback that will toggle fullscreen
        • isFullscreen argument for when fullscreen is active
        renderFullscreenButton: (onClick, isFullscreen) => (
          <Fullscreen onClick={onClick} isFullscreen={isFullscreen} />
    • useWindowKeyDown: Boolean, default true

      • If true, listens to keydown events on window (window.addEventListener)
      • If false, listens to keydown events on image gallery element (imageGalleryElement.addEventListener)


    The following functions can be accessed using refs

    • play(): plays the slides
    • pause(): pauses the slides
    • fullScreen(): activates full screen
    • exitFullScreen(): deactivates full screen
    • slideToIndex(index): slides to a specific index
    • getCurrentIndex(): returns the current index


    Each PR should be specific and isolated to the issue you're trying to fix. Please do not stack features/chores/refactors/enhancements in one PR. Describe your feature/implementation in the PR. If you're unsure its useful or if it is a major change, please open an issue first and get feedback.

    • Follow eslint provided
    • Comment your code
    • Write clean code

    Build the example locally (requires node >= 12.13)

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

    Then open localhost:8001 in a browser.




    npm i react-image-gallery

    DownloadsWeekly Downloads






    Unpacked Size

    142 kB

    Total Files


    Last publish


    • linxtion