carlobambo/react-image-gallery

React carousel image gallery component with thumbnail support 🖼

React Image Gallery

Live Demo (try it on mobile for swipe support)

linxtion.com/demo/react-image-gallery

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

Features

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

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";

Example

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} />;
  }
}

Props

• 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)
    • thumbnailHeight - image height (html5 attribute)
    • thumbnailWidth - image width (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

  • Use this to render a custom left nav control
  • Passes onClick callback that will slide to the previous item and disabled argument for when to disable the nav

    renderLeftNav(onClick, disabled) {
      return (
        <button
          className='image-gallery-custom-left-nav'
          disabled={disabled}
          onClick={onClick}/>
      )
    }

• renderRightNav: Function, custom right nav component

  • Use this to render a custom right nav control
  • Passes onClick callback that will slide to the next item and disabled argument for when to disable the nav

    renderRightNav(onClick, disabled) {
      return (
        <button
          className='image-gallery-custom-right-nav'
          disabled={disabled}
          onClick={onClick}/>
      )
    }

• renderPlayPauseButton: Function, play pause button component

  • Use this to render a custom play pause button
  • Passes onClick callback that will toggle play/pause and isPlaying argument for when gallery is playing

    renderPlayPauseButton: (onClick, isPlaying) => {
      return (
        <button
          type='button'
          className={
            `image-gallery-play-button${isPlaying ? ' active' : ''}`}
          onClick={onClick}
        />
      );
    }

• renderFullscreenButton: Function, custom fullscreen button component

  • Use this to render a custom fullscreen button
  • Passes onClick callback that will toggle fullscreen and isFullscreen argument for when fullscreen is active

    renderFullscreenButton: (onClick, isFullscreen) => {
      return (
        <button
          type='button'
          className={
            `image-gallery-fullscreen-button${isFullscreen ? ' active' : ''}`}
          onClick={onClick}
        />
      );
    },

• 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)

Functions

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

Contributing

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.

License

MIT