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.

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

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

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

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

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

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

• itemsStyle - accepts an object.

• textBoxStyle accepts an object.

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.