React Carousel Slider

A React component that endeavors to provide flexbility for customizing carousel/slider.

Demo & Examples

carr1005.github.io/react-carousel-slider/index.html

Having a quick try:

Installation

Install it from npm.

npm install react-carousel-slider

As ES module:

import CarouselSlider from "react-carousel-slider"

As CommonJS module:

var CarouselSlider = require("react-carousel-slider")

The UMD build:

<script src="https://unpkg.com/react-carousel-slider/umd/react-carousel-slider.js"></script>

Mobile Compatible

Touch events would be rigistered on this component automatically when mobile device viewport is detected, so the drag event is also available on mobile.

Usage

We could render a component with the slideItems prop which accepts an array of objects with the specific simple sturcture and keys in default style. If the slider doesn't show the image when you are testing with local images, make sure if you do it in the right way.

import React, {Component} from 'react'
import CarouselSlider from 'react-carousel-slider';

class App extends Component {
    render() {
    
        let data = [
            {
                des: "1",
                imgSrc: "https://i.imqur.com/yourImage.jpg"
            },
            {
                des: "2",
                imgSrc: "https://i.imqur.com/yourImage2.jpg"
            }
        ];
        
        return <CarouselSlider slideItems = {data} />;
    }
}

Or give an array of your own regular React elements to slideCpnts prop, this lets our slide have availability to contain a clickable link. Even cooperating with <Link> component of React Router library for client side routing is possible.

Click the slide and observe the address bar in CodeSandbox:

import React, {Component} from 'react'
import CarouselSlider from 'react-carousel-slider';
import {BrowserRouter as Router, Link } from 'react-router-dom';

class App extends Component {
    render() {
    
        let jsonData = require('./slidesExample.json');
        /*
            {
                "items": [
                    {
                        "des": "1",
                        "imgSrc": "https://i.imqur.com/yourImage.jpg"
                    },
                    {
                        "des": "2",
                        "imgSrc": "https://i.imqur.com/yourImage2.jpg"
                    }
                ] 
            }
        */
        
        let items = jsonData.items.map((item, index) => 
            <Link to = {'/' + item.des} >
                <img src = {item.imgSrc} ></img>
                <p>{item.des}</p>
            </Link>
        );
        
        return (<Router>
            <CarouselSlider slideCpnts = {items} />
        </Router>);
    }
}

Allowable Props

• slideItems
• slideCpnts

All props below are optional, default setting is applied if we don't specify ours.

The Key without prefixng a * is pure css property, what be filled in column Value are just recommended because of the anticipated purpose, feel free to try if things are under control.

• manner
• accEle
• dotsSetting
• buttonSetting
• lBtnCpnt
• rBtnCpnt
• sliderBoxStyle
• itemsStyle
• textBoxStyle

---

• slideItems - accepts an array of objects, specific structure and keys are required.

    [
        {
            des: "1",
            imgSrc: "https://i.imqur.com/yourImage.jpg"
        },
        {
            des: "2",
            imgSrc: "https://i.imqur.com/yourImage2.jpg"
        }
    ]

• slideCpnts - accepts an array of regular React elements, the <img></img> element and available image source are required, we have the default style for <p> block, override it by specifying your own with using inline-styles.

    let textBoxStyle = {
        width: "50%",
        background: "transparent",
        textAlign: "right",
        color: "black"
    };
    
    let items = jsonData.items.map((item, index) => 
        <div>
            <img src = {item.imgSrc} ></img>
            <p style = {textBoxStyle} >{item.des}</p>
        </div>
    );

Allowable Props - Optional

• manner - accepts an object, defines how your carousel / slider performs animating.

Key	Value	Default	Description & Notice
* autoSliding	{interval: "?s" }	false	Interval between sliding, suffix 's'(seconds) is required, only giving true is ineffectual.
* circular	true | false	true
* duration	"?s"	"0.5s"

---

• accEle - accepts an object, to decide whether accessory elements show or not.

Key	Value	Default	Description & Notice
* button	true | false	true	You may want to set it to false in some situations, e.g., in mobile device viewport.
* dots	true | false	true
* flag	true | false	false

---

• dotsSetting - accepts an object, this prop would be ignored if corresponding value of dots is set to false in prop accEle.

Key	Value	Default	Description & Notice
* placeOn	top | bottom | beneath		Only options in column Value are available, fine-tune the position with margin- property in style below.
* style	{}

---

Available keys and expected values in object which dotsSetting.style accepts.

Key	Value	Default	Description & Notice
* dotSpace	<length>	"5px"	Space between dots.
* dotSize	<length>	"10px"	For width and height of dot.
* dotColor	rgb() | rgba() | hex value	"#dbdbdb"
* currDotSize	<length>	"12px"	For width and height of current dot.
* currDotColor	rgb() | rgba() | hex value	"#3897f0"
* marginTop	<length>	"15px"	To fine-tune the vertical position when placeOn is set to top.
* marginBottom	<length>	"15px"	To fine-tune the vertical position when placeOn is set to bottom.

---

• buttonSetting - accepts an object, this prop would be ignored if corresponding value of button is set to false in prop accEle. We use content: '\003c', content: '\003e' to present buttons, you may want to design your own by utilizing props lBtnCpnt and rBtnCpnt.

Key	Value	Default	Description & Notice
* placeOn	top-left | top-right | middle-inside | middle-outside | bottom-left | bottom-right | bottom-beneath	"top-left"	Only options in column Value are available, fine-tune the position with margin property in style.left / style.right. Notice about option middle-outside: - If your sliderBox width is narrow, maybe you neet parent element like: <div style={{ width: "?px", margin: "0 auto", position: "relative" }}> </div> to confine the absolute positioned button. - This option would not function with hoverEvent property below.
* hoverEvent	true | false	false	Buttons are only visible when the cursor hover on the slider.
* style	{left: {}, right: {}}

Recommended keys and values in object which buttonSetting.style.left or buttonSetting.style.right accepts.

Key	Value	Default	Description & Notice
color	hex value	"#ffffff"
background	rgb() | rgba() | hex value	"#757575"
height	<length>	"30px"
width	<length>	"30px"
margin	<length>	"10px"
fontSize	<length>	"20px"
borderRadius	<length> | <percentage>	"2px"
border	All border property	"none"

---

• lBtnCpnt, rBtnCpnt - Both accepts a regular React element. Use these props to give our own designed button, style property in buttonSetting would be ignored. See the example in Demo.

---

• sliderBoxStyle - accepts an object.

Key	Value	Default	Description & Notice
height	<length> | <percentage>	"400px"
width	<length> | <percentage>	"90%"
background	rgb() | rgba() | hex value	"#EEEEEE"
border	All available properties	none

---

• itemsStyle - accepts an object.

Key	Value	Default	Description & Notice
height	<length> | <percentage>	"80%"
padding	<length> | <percentage>	"3px"
background	rgb() | rgba() | hex value	"#EEEEEE"
margin	0px ?px	"0px 40px"	To give the space between slides , only accept value in form 0px ?px now.
minWidth	<length> | <percentage>	100px	For the situation that the source of image is not provided, and maybe you want to let your slide still have room. See more explaination in the Demo.

---

• textBoxStyle accepts an object.

Key	Value	Default	Description & Notice
color	hex value	"#ffffff"
padding	<length> | <percentage>	"10px"
background	rgb() | rgba() | hex value	"rgba(117, 117, 117, .6)"
borderRadius	<length> | <percentage>	"2px"
textAlign	left | right | center	"center"
width	<length> | <percentage>	"75%"
top	<length> | <percentage>	"80%"	To adjust vertical position. 50% for centering.
fontSize	<length>
fontWeight	All available properties

Additional Know How - Loading Local Images

While testing this component with local images, some problems may appear because we are just new to develop in React with webpack.

If we have a directory structure like:

- app
    |___ demo
    |      |___ images
    |      |        |___ yourImage1.jpg
    |      |        |___ yourImage2.jpg
    |      |
    |      |___index.js
    |
    |
    |___ src
    | 
    ...

In /app/demo/index.js, provide image sources with relative paths such as:

    let data = [
        {
            des: "1",
            imgSrc: "./images/yourImage1.jpg"
        },
        {
            des: "2",
            imgSrc: "./images/yourImage2.jpg"
        }
    ];

    return <CarouselSlider slideItems = {data} />;

The images certainly won't be rendered. This is not caused by the practice in our component, it caused by the bundling mechanism that webpack works. We could have more tests:

    let data = [
        {
            des: "1",
            imgSrc: "./images/yourImage1.jpg"
        },
        {
            des: "2",
            imgSrc: "./images/yourImage2.jpg"
        }
    ];
    
    let imgOne = (<img src = {data[0].imgSrc}></img>);
    let imgTwo = (<img src = {require(data[0].imgSrc)}></img>);
    return (<div>
        {imgOne}
        {imgTwo}
    </div>);

Neither of image elements above can load and render the image succesfully.

Here are some points that we need to know:

• Webpack needs to know what files to bundle at compile time, but dynamic image path in expression would only know in runtime.

• In fact, there is a tricky way that gives concatenated string containing expression to require() to include the images for bundling. But to properly render the images, it still need to do something on loaders in webpack.config.js. We are not going this way in this component behind.

• To get the proper image sources from local and pass to our carousel slider component, here is a good way with reqiure.context:

/* In the directory structure we assume above*/

let data = [
        {
            des: "1",
            imgSrc: "yourImage1.jpg"
        },
        {
            des: "2",
            imgSrc: "yourImage2.jpg"
        }
    ];
    
    let assetsPath = require.context('./images', false, /\.(png|jpe?g|svg)$/);
    
    // Substituting the imgSrc from file name in ./images to their corresponding path after they are bundled.
    data.map((item, index) => {
        // console.log(assetsPath.keys(), assetsPath.id);
        item.imgSrc = assetsPath('./' + item.imgSrc);
    });
    
    return <CarouselSlider slideItems = {data} />;

License

MIT Licensed. Copyright (c) Carr.W 2018.