Wondering what’s next for npm?Check out our public roadmap! »

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

    1.0.9 • Public • Published

    React Carousel Image Gallery

    npm version Download Count

    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)
    • Lightweight ~7kb 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)
        • 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

    • 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

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

      • 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}
            />
          );
        },
    • useWindowKeyDown: Boolean, default true

      • If false, keydown events will be listened for on the image gallery

    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

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

    Then open localhost:8001 in a browser.

    License

    MIT

    Install

    npm i react-image-gallery

    DownloadsWeekly Downloads

    69,474

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    141 kB

    Total Files

    11

    Last publish

    Collaborators

    • avatar