React carousel image gallery component with thumbnail and mobile support

React Carousel Image Gallery

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

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

Features of react-image-gallery

Mobile Swipe Gestures
Thumbnail Navigation
Fullscreen Support
Custom Rendered Slides
Responsive Design
Tons of customization options (see props below)
Lightweight ~8kb (gzipped, excluding react)

Getting started

npm install react-image-gallery

Style import

# SCSS
@import "node_modules/react-image-gallery/styles/scss/image-gallery.scss";

# CSS
@import "node_modules/react-image-gallery/styles/css/image-gallery.css";

# Webpack
import "react-image-gallery/styles/css/image-gallery.css";

# Stylesheet with no icons
node_modules/react-image-gallery/styles/scss/image-gallery-no-icon.scss
node_modules/react-image-gallery/styles/css/image-gallery-no-icon.css

Example

Need more example? See example/app.js

import ImageGallery from 'react-image-gallery';

class MyComponent extends React.Component {

  render() {

    const images = [
      {
        original: 'http://lorempixel.com/1000/600/nature/1/',
        thumbnail: 'http://lorempixel.com/250/150/nature/1/',
      },
      {
        original: 'http://lorempixel.com/1000/600/nature/2/',
        thumbnail: 'http://lorempixel.com/250/150/nature/2/'
      },
      {
        original: 'http://lorempixel.com/1000/600/nature/3/',
        thumbnail: 'http://lorempixel.com/250/150/nature/3/'
      }
    ]

    return (
      <ImageGallery items={images} />
    );
  }

}

Props

items: (required) Array of objects, see example above,
- Available Properties
  - original - image src url
  - thumbnail - image thumbnail src url
  - originalClass - custom image class
  - thumbnailClass - custom thumbnail class
  - renderItem - Function for custom renderer (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
  - imageSet - array of <source> using <picture> element (see app.js for example)
  - 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
showBullets: Boolean, default false
showIndex: Boolean, default false
autoPlay: Boolean, default false
disableThumbnailScroll: Boolean, default false
- disables the thumbnail container from adjusting
disableArrowKeys: Boolean, default false
disableSwipe: Boolean, default false
defaultImage: 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
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.
preventDefaultTouchmoveEvent: Boolean, default false
- An option to prevent the browser's touchmove event (stops the gallery from scrolling up or down when swiping)
startIndex: Number, default 0
onImageError: Function, callback(event)
- overrides defaultImage
onThumbnailError: Function, callback(event)
- overrides defaultImage
onThumbnailClick: Function, callback(event, index)
onImageLoad: Function, callback(event)
onSlide: Function, callback(currentIndex)
onScreenChange: Function, callback(fullscreenElement)
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
- On a specific item [{thumbnail: '...', renderItem: this.myRenderItem}]
  or
- As a prop passed into ImageGallery to completely override _renderItem, see source for reference
renderThumbInner: Function, custom thumbnail rendering
- On a specific item [{thumbnail: '...', renderThumbInner: this.myRenderThumbInner}]
  or
- 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}
      />
    );
  },

Functions

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

Follow eslint provided
Comment your code
Describe your feature/implementation in the pullrequest
Write clean code

Build the example locally

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