josephjbliss/react-image-gallery

Responsive and flexible carousel component with thumbnail support 🖼

React Image Gallery

Live Demo (try it on mobile for swipe support)

Live demo: linxtion.com/demo/react-image-gallery

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

Features of react-image-gallery

• Mobile friendly
• Thumbnail navigation
• Fullscreen support
• Custom rendered slides
• Responsive design

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

# 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 {

  handleImageLoad(event) {
    console.log('Image loaded ', event.target)
  }

  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}
        slideInterval={2000}
        onImageLoad={this.handleImageLoad}/>
    );
  }

}

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
    • originalAlt - image alt
    • thumbnailAlt - thumbnail image alt
    • thumbnailLabel - label for thumbnail
    • description - description for image
    • srcSet - image srcSet
    • sizes - image sizes
• 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
• 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
• slideOnThumbnailHover: Boolean, default false
  • slides to the currently hovered thumbnail
• 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
• onImageError: Function, callback(event)
  • overrides defaultImage
• onThumbnailError: Function, callback(event)
  • overrides defaultImage
• indexSeparator: String, default ' / ', ignored if showIndex is false
• slideDuration: Integer, default 450
  • transition duration during image slide in milliseconds
• slideInterval: Integer, default 3000
• startIndex: Integer, default 0
• onImageLoad: Function, callback(event)
• onSlide: Function, callback(currentIndex)
• onScreenChange: Function, callback(fullscreenElement)
• onPause: Function, callback(currentIndex)
• onPlay: Function, callback(currentIndex)
• onClick: Function, callback(event)
• 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
  • As a prop on a specific item [{thumbnail: '...', renderItem: '...'}]
  • As a prop passed into ImageGallery to completely override _renderItem, see original below

      _renderItem(item) {
        const onImageError = this.props.onImageError || this._handleImageError
    
        return (
          <div className='image-gallery-image'>
            <img
                src={item.original}
                alt={item.originalAlt}
                srcSet={item.srcSet}
                sizes={item.sizes}
                onLoad={this.props.onImageLoad}
                onError={onImageError.bind(this)}
            />
            {
              item.description &&
                <span className='image-gallery-description'>
                  {item.description}
                </span>
            }
          </div>
        )
      }

• 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(): continuous plays if image is not hovered
• pause(): pauses the slides
• fullScreen(): activates full screen
• exitFullScreen(): deactivates full screen
• slideToIndex(index): slides to a specific index
• getCurrentIndex(): returns the current index

Notes

• Feel free to contribute and or provide feedback!

Build the example locally

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

Then open localhost:8001 in a browser.

License

MIT