/react-image-gallery

React carousel image gallery component with thumbnail support 🖼

Primary LanguageJavaScriptMIT LicenseMIT

React Image Gallery

npm version Download Count Bundle size

Live Demo (try it on mobile for swipe support)

linxtion.com/demo/react-image-gallery

demo gif

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)

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

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