Newport product images gallery with mobile and touch support.
- Mobile swipe gestures
- Thumbnail navigation
- Fullscreen support
- Custom rendered slides
- RTL support
- Responsive design
- Customization options (see props below)
Newport Product Gallery requires React 16.0.0 or later.
npm install newport-product-gallery
To avoid React version conflicts add --legacy-peer-deps
npm install newport-product-gallery --legacy-peer-deps
# SCSS
@import "~newport-product-gallery/styles/scss/image-gallery.scss";
# CSS
@import "~newport-product-gallery/styles/css/image-gallery.css";
Need more example? See example/app.js
import ImageGallery from 'newport-product-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} />;
}
}
-
items
: (required) Array of objects, see example above,- Available Properties
original
- image src urlthumbnail
- image thumbnail src urlfullscreen
- 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 classthumbnailClass
- custom thumbnail classrenderItem
- Function for custom rendering a specific slide (see renderItem below)renderThumbInner
- Function for custom thumbnail renderer (see renderThumbInner below)originalAlt
- image altthumbnailAlt
- thumbnail image altoriginalTitle
- image titlethumbnailTitle
- thumbnail image titlethumbnailLabel
- label for thumbnaildescription
- description for imagesrcSet
- image srcset (html5 attribute)sizes
- image sizes (html5 attribute)bulletClass
- extra class for the bullet of the itembulletOnClick
-callback({item, itemIndex, currentIndex})
- A function that will be called upon bullet click.
- Available Properties
-
infinite
: Boolean, defaulttrue
- infinite sliding
-
lazyLoad
: Boolean, defaultfalse
-
showNav
: Boolean, defaulttrue
-
showThumbnails
: Boolean, defaulttrue
-
thumbnailPosition
: String, defaultbottom
- available positions:
top, right, bottom, left
- available positions:
-
showFullscreenButton
: Boolean, defaulttrue
-
useBrowserFullscreen
: Boolean, defaulttrue
- if false, fullscreen will be done via css within the browser
-
useTranslate3D
: Boolean, defaulttrue
- if false, will use
translate
instead oftranslate3d
css property to transition slides
- if false, will use
-
showPlayButton
: Boolean, defaulttrue
-
isRTL
: Boolean, defaultfalse
- if true, gallery's direction will be from right-to-left (to support right-to-left languages)
-
showBullets
: Boolean, defaultfalse
-
showIndex
: Boolean, defaultfalse
-
autoPlay
: Boolean, defaultfalse
-
disableThumbnailScroll
: Boolean, defaultfalse
- disables the thumbnail container from adjusting
-
disableKeyDown
: Boolean, defaultfalse
- disables keydown listener for keyboard shortcuts (left arrow, right arrow, esc key)
-
disableSwipe
: Boolean, defaultfalse
-
disableThumbnailSwipe
: Boolean, defaultfalse
-
onErrorImageURL
: String, defaultundefined
- 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 ifshowIndex
is false -
slideDuration
: Number, default450
- transition duration during image slide in milliseconds
-
swipingTransitionDuration
: Number, default0
- transition duration while swiping in milliseconds
-
slideInterval
: Number, default3000
-
slideOnThumbnailOver
: Boolean, defaultfalse
-
flickThreshold
: Number (float), default0.4
- Determines the max velocity of a swipe before it's considered a flick (lower = more sensitive)
-
swipeThreshold
: Number, default30
- 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, defaultfalse
- Automatically calls stopPropagation on all 'swipe' events.
-
startIndex
: Number, default0
-
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 overriderenderItem
, 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
- On a specific item
-
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 itemdisabled
boolean for when the nav is disabled
renderLeftNav: (onClick, disabled) => ( <LeftNav onClick={onClick} disabled={disabled} /> )
- See
-
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 itemdisabled
boolean for when the nav is disabled
renderRightNav: (onClick, disabled) => ( <RightNav onClick={onClick} disabled={disabled} /> )
- See
-
renderPlayPauseButton
: Function, play pause button component- See
<PlayPause />
- Use this to render a custom play pause button
- Args:
onClick
callback that will toggle play/pauseisPlaying
boolean for when gallery is playing
renderPlayPauseButton: (onClick, isPlaying) => ( <PlayPause onClick={onClick} isPlaying={isPlaying} /> )
- See
-
renderFullscreenButton
: Function, custom fullscreen button component- See
<Fullscreen />
- Use this to render a custom fullscreen button
- Args:
onClick
callback that will toggle fullscreenisFullscreen
argument for when fullscreen is active
renderFullscreenButton: (onClick, isFullscreen) => ( <Fullscreen onClick={onClick} isFullscreen={isFullscreen} /> ),
- See
-
useWindowKeyDown
: Boolean, defaulttrue
- If
true
, listens to keydown events on window (window.addEventListener) - If
false
, listens to keydown events on image gallery element (imageGalleryElement.addEventListener)
- If
The following functions can be accessed using refs
play()
: plays the slidespause()
: pauses the slidesfullScreen()
: activates full screenexitFullScreen()
: deactivates full screenslideToIndex(index)
: slides to a specific indexgetCurrentIndex()
: returns the current index
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
git clone https://github.com/deus-newport/newport-product-gallery.git
cd newport-product-gallery
npm install --global yarn
yarn install
yarn start
Then open localhost:3030
in a browser.
MIT