carousel

Dependency-free React carousel component with support for lazy loading

Mar 31, 2021
Dependency-free React carousel component with support for lazy loading

react-gallery-carousel

Dependency-free React carousel component with support for lazy loading, pinch zoom, touch swiping, mouse dragging, velocity detection, maximization, thumbnails, keyboard navigation and accessibility.

View Demo View Github

68747470733a2f2f796966616e61692e73332d61702d736f757468656173742d322e616d617a6f6e6177732e636f6d2f7267632f64656d6f5f7472616e736974696f6e2e676966

68747470733a2f2f796966616e61692e73332d61702d736f757468656173742d322e616d617a6f6e6177732e636f6d2f7267632f64656d6f5f6e6f6e5f6d6178696d697a65642e6a7067

68747470733a2f2f796966616e61692e73332d61702d736f757468656173742d322e616d617a6f6e6177732e636f6d2f7267632f64656d6f5f6d6178696d697a65642e6a7067

68747470733a2f2f796966616e61692e73332d61702d736f757468656173742d322e616d617a6f6e6177732e636f6d2f7267632f6c69676874686f7573655f7265706f72742e6a7067

Install

npm install --save react-gallery-carousel

OR

yarn add react-gallery-carousel

Usage

import React from 'react'; import Carousel from 'react-gallery-carousel'; import 'react-gallery-carousel/dist/index.css'; const App = () => { const images = [900, 800, 700, 600, 500].map((size) => ({ src: `https://placedog.net/${size}/${size}` })); return ( <Carousel images={images} /> ); }; export default App;

Props

To customize the carousel, use the following props:

NameTypeDefaultDescription
imagesArrayundefinedArray of image(s) to be placed in the carousel. Each image object (e.g. example object) in the array has a required attribute 'src'.
childrennode or Array of nodesundefinedHTML element(s) to be placed into the carousel, but it (they) will be placed only if the 'images' prop is falsy.
indexNumberundefinedCurrent (0-indexed) index of the slides of the carousel as a whole number starting from 0.
isRTLBooleanfalseIf true, the slides of the carousel starts from the right (and also auto plays from the right to the left).
isLoopBooleantrueIf true, the carousel form a loop (i.e. going left from the left-most slide lands at the right-most slide, and vice versa) from the ribbon of slides.
isMaximizedBooleanfalseIf true, the carousel is maximized initially.
shouldLazyLoadBooleantrueIf true, images that are not yet in the viewport of the carousel will be lazy loaded, except the 2 adjacent images from either side of the carousel which will be preloaded.
canAutoPlayBooleantrueIf true, the carousel has auto play capability.
isAutoPlayingBooleanfalseIf true, the carousel auto plays initially.
autoPlayIntervalNumber5000Interval of the auto play (in milliseconds).
hasTransitionBooleantrueIf false, the carousel does not have transition in moving between slides.
swipeThresholdNumber0.1Threshold swipe distance (in percentage of the width of the viewport of the carousel) to move to the previous or the next slide.
swipeRollbackSpeedNumber0.1Speed of the transition (in pixels per millisecond) in moving back to the current slide after a swipe smaller than swipeThreshold.
transitionSpeedNumber1Speed of the transition (in pixels per millisecond) in moving to the previous or the next slide on non-swipe updates on the carousel.
transitionDurationLimitNumber750Limit of transition duration (in milliseconds). The limit is used to flatten transition duration, where the maximum transition duration infinitely approaches this value.
transitionDurationMinNumber250Minimum transition duration (in milliseconds). Transition duration can be set to be a constant with transitionDurationMin === transitionDurationMax.
transitionDurationMaxNumberundefinedMaximum transition duration (in milliseconds). It will have precedence over transitionDurationMin, if transitionDurationMin > transitionDurationMax.
widgetsHasShadowBooleanfalseIf true, the following widgets (with *) have shadows. (Note: if true, the transition will tend to drop frames when there are a large number of slides.)
hasLeftButton *Boolean or String'centerLeft'If false, the carousel does not show left button. Its position can be specified by one of small widget positions.
hasRightButton *Boolean or String'centerRight'If false, the carousel does not show right button. Its position can be specified by one of small widget positions.
hasMediaButton *Boolean or String'topLeft'If false, the carousel does not show media button (i.e. play/pause button). Its position can be specified by one of small widget positions. If the value of 'canAutoPlay' is falsy, media button will not be shown on the carousel.
hasSizeButton *Boolean or String'topRight'If false, the carousel does not show size button (i.e. maximize/minimize button). Its position can be specified by one of small widget positions.
hasIndexBoard *Boolean or String'topCenter'If false, the carousel does not show index board (i.e. currentIndex / totalNumberOfSlides). Its position can be specified by one of small widget positions.
hasDotButtons *Boolean or StringfalseIf false, the carousel does not show dot buttons (i.e. array of dots indicating the current slide in relation to other slides). Its position can be specified by one of large widget positions.
hasCaptions *Boolean or StringfalseIf false, the carousel does not show caption for each image. Its position can be specified by one of large widget positions.
hasThumbnailsBooleantrueIf false, the carousel does not show thumbnails at the bottom.
hasLeftButtonAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show left button. Its position can be specified by one of small widget positions. It overrides 'hasLeftButtons' prop for the maximized carousel. If not specified, the value of 'hasLeftButtons' will be used.
hasRightButtonAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show right button. Its position can be specified by one of small widget positions. It overrides 'hasRightButtons' prop for the maximized carousel. If not specified, the value of 'hasLeftButtons' will be used.
hasMediaButtonAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show media button (i.e. play/pause button). Its position can be specified by one of small widget positions. It overrides 'hasMediaButton' prop for the maximized carousel. If not specified, the value of 'hasMediaButton' will be used. If the value of 'canAutoPlay' is falsy, media button will not be shown on the maximized carousel.
hasSizeButtonAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show size button (i.e. maximize/minimize button). Its position can be specified by one of small widget positions. It overrides 'hasSizeButton' prop for the maximized carousel. If not specified, the value of 'hasSizeButton' will be used.
hasIndexBoardAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show index board (i.e. currentIndex / totalNumberOfSlides). Its position can be specified by one of small widget positions. It overrides 'hasIndexBoard' prop for the maximized carousel. If not specified, the value of 'hasIndexBoard' will be used.
hasDotButtonsAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show dot buttons (i.e. array of dots indicating the current slide in relation to other slides). Its position can be specified by one of large widget positions. It overrides 'hasDotButtons' prop for the maximized carousel. If not specified, the value of 'hasDotButtons' will be used.
hasCaptionsAtMax *Boolean or StringundefinedIf false, the maximized carousel does not show caption for each image. Its position can be specified by one of large widget positions. It overrides 'hasCaptions' prop for the maximized carousel. If not specified, the value of 'hasCaptions' will be used.
hasThumbnailsAtMaxBooleanundefinedIf false, the maximized carousel does not show thumbnails at the bottom. It overrides 'hasThumbnails' for the maximized carousel. If not specified, the value of 'hasThumbnails' will be used.
leftIconnodeundefinedLeft icon (HTML element) to be placed into the left ArrowButton.
rightIconnodeundefinedRight icon (HTML element) to be placed into the right ArrowButton.
playIconnodeundefinedPlay icon (HTML element) to be placed into the MediaButton.
pauseIconnodeundefinedPause icon (HTML element) to be placed into the MediaButton.
minIconnodeundefinedMinimize icon (HTML element) to be placed into the SizeButton.
maxIconnodeundefinedMaximize icon (HTML element) to be placed into the SizeButton.
activeIconnodeundefinedActive dot icon (HTML element) to be placed into the active DotButton indicating the current slide.
passiveIconnodeundefinedPassive dot icon (HTML element) to be placed into the passive DotButton indicating all non-current slide(s).
shouldSwipeOnMouseBooleantrueIf true, the carousel can be swiped by the cursor using a mouse or a track pad.
shouldMaximizeOnClickBooleanfalseIf true, the carousel can be maximized by clicking.
shouldMinimizeOnClickBooleanfalseIf true, the carousel can be minimized by clicking.
shouldMinimizeOnSwipeDownBooleantrueIf true, the carousel can be minimized by touch swiping down.
onIndexChangeFunction() => {}Callback function invoked when the current index of the slides of the carousel is being updated. (Note: it is called regardless of whether index value's before and after are the same.)
objectFitString'cover'CSS 'object-fit' style to be placed on each image, on the non-maximized carousel.
objectFitAtMaxString'contain'CSS 'object-fit' style to be placed on each image, on the maximized carousel.
zIndexAtMaxNumberundefinedCSS 'z-index' attribute to be placed on the maximized carousel.
classNameStringundefinedClass name(s) to be placed on the non-maximized carousel.
styleObjectundefinedInline style(s) to be placed on the non-maximized carousel.

Local Development

  1. In a terminal tab, run rollup to watch the src/ directory and to automatically compile the local version of react-gallery-carousel into the dist/ directory.
yarn start
  1. In another terminal tab, run create-react-app dev server to serve the example in the example/ directory, which is dependent on the local version of react-gallery-carousel.
cd example yarn start

(Note: it is not helpful to run either of these commands in the background, because you will miss out on errors and warnings.)

Definitions

  • Developer users: developers who use this component.
  • Users: end users of the products which use this component.

Image Object Example

{ src: `https://placedog.net/700/420?id=1`, // required srcset: `https://placedog.net/400/240?id=1 400w, https://placedog.net/700/420?id=1 700w, https://placedog.net/1000/600?id=1 1000w`, sizes: '(max-width: 1000px) 400px, (max-width: 2000px) 700px, 1000px', alt: `Dogs are domesticated mammals, not natural wild animals. They were originally bred from wolves. They have been bred by humans for a long time, and were the first animals ever to be domesticated.`, thumbnail: `https://placedog.net/100/60?id=1` }

Small Widget Positions

[ 'topLeft', 'topCenter', 'topRight', 'centerLeft', 'centerCenter', 'centerRight', 'bottomLeft', 'bottomCenter','bottomRight' ]

Large Widget Positions

['top', 'bottom']

GitHub

https://github.com/yifaneye/react-gallery-carousel

Recommended