react-multi-carousel 👋

Production-ready, lightweight fully customizable React carousel component that rocks supports multiple items and SSR(Server-side rendering).

Hello world!

We are on a very excited journey towards version 3.0 of this component which will be rewritten in hooks/context completely. It means smaller bundle size, performance improvement and easier customization of the component and so many more benefits.

It would mean so much if you could provide help towards the further development of this project as we do this open source work in our own free time especially during this covid-19 crisis.

If you are using this component seriously, please donate or talk to your manager as this project increases your income too. It will help us make releases, fix bugs, fulfill new feature requests faster and better.

Become a backer/sponsor to get your logo/image on our README on Github with a link to your site.

Features.

• Server-side rendering
• Infinite mode
• Dot mode
• Custom animation
• AutoPlay mode
• Auto play interval
• Supports images, videos, everything.
• Responsive
• Swipe to slide
• Mouse drag to slide
• Keyboard control to slide
• Multiple items
• Show / hide arrows
• Custom arrows / control buttons
• Custom dots
• Custom styling
• Accessibility support
• Center mode.
• Show next/previous set of items partially
• RTL support

Shoutouts 🙏

Big thanks to BrowserStack for letting the maintainers use their service to debug browser issues.

Documentation

Other important links.

• Code sandbox
• Contributing
• Changelog
• Releases
• TypeScript usage
• SSR demo

Bundle size

Bundle-size. 2.5kB

Demo.

Documentation is here.

Demo for the SSR https://react-multi-carousel.now.sh/

Try to disable JavaScript to test if it renders on the server-side.

Codes for SSR at github.

Codes for the documentation at github.

Install

$ npm install react-multi-carousel --save

import Carousel from 'react-multi-carousel';
import 'react-multi-carousel/lib/styles.css';

How the SSR mode works?

Codes for SSR at github.

• Demo for the SSR are at here
• Try to disable JavaScript to test if it renders on the server-side.

Here is a lighter version of the library for detecting the user's device type alternative

You can choose to only bundle it on the server-side.

Minimum working set up.

import Carousel from "react-multi-carousel";
import "react-multi-carousel/lib/styles.css";
const responsive = {
  superLargeDesktop: {
    // the naming can be any, depends on you.
    breakpoint: { max: 4000, min: 3000 },
    items: 5
  },
  desktop: {
    breakpoint: { max: 3000, min: 1024 },
    items: 3
  },
  tablet: {
    breakpoint: { max: 1024, min: 464 },
    items: 2
  },
  mobile: {
    breakpoint: { max: 464, min: 0 },
    items: 1
  }
};
<Carousel responsive={responsive}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</Carousel>;

Common Usage

import Carousel from "react-multi-carousel";
import "react-multi-carousel/lib/styles.css";

const responsive = {
  desktop: {
    breakpoint: { max: 3000, min: 1024 },
    items: 3,
    slidesToSlide: 3 // optional, default to 1.
  },
  tablet: {
    breakpoint: { max: 1024, min: 464 },
    items: 2,
    slidesToSlide: 2 // optional, default to 1.
  },
  mobile: {
    breakpoint: { max: 464, min: 0 },
    items: 1,
    slidesToSlide: 1 // optional, default to 1.
  }
};
<Carousel
  swipeable={false}
  draggable={false}
  showDots={true}
  responsive={responsive}
  ssr={true} // means to render carousel on server-side.
  infinite={true}
  autoPlay={this.props.deviceType !== "mobile" ? true : false}
  autoPlaySpeed={1000}
  keyBoardControl={true}
  customTransition="all .5"
  transitionDuration={500}
  containerClass="carousel-container"
  removeArrowOnDeviceType={["tablet", "mobile"]}
  deviceType={this.props.deviceType}
  dotListClass="custom-dot-list-style"
  itemClass="carousel-item-padding-40-px"
>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</Carousel>;

Custom Arrows.

You can pass your own custom arrows to make it the way you want, the same for the position. For example, add media query for the arrows to go under when on smaller screens.

Your custom arrows will receive a list of props/state that's passed back by the carousel such as the currentSide, is dragging or swiping in progress.

Code

const CustomRightArrow = ({ onClick, ...rest }) => {
  const {
    onMove,
    carouselState: { currentSlide, deviceType }
  } = rest;
  // onMove means if dragging or swiping in progress.
  return <button onClick={() => onClick()} />;
};
<Carousel customRightArrow={<CustomRightArrow />} />;

Custom button group.

This is very useful if you don't want the dots, or arrows and you want to fully customize the control functionality and styling yourself.

Code

const ButtonGroup = ({ next, previous, goToSlide, ...rest }) => {
  const { carouselState: { currentSlide } } = rest;
  return (
    <div className="carousel-button-group"> // remember to give it position:absolute
      <ButtonOne className={currentSlide === 0 ? 'disable' : ''} onClick={() => previous()} />
      <ButtonTwo onClick={() => next()} />
      <ButtonThree onClick={() => goToSlide(currentSlide + 1)}> Go to any slide </ButtonThree>
    </div>
  );
};
<Carousel arrows={false} customButtonGroup={<ButtonGroup />}>
  <ItemOne>
  <ItemTwo>
</Carousel>

renderButtonGroupOutside

Passing this props would render the button group outside of the Carousel container. This is done using React.fragment

<div className='my-own-custom-container'>
  <Carousel arrows={false} renderButtonGroupOutside={true} customButtonGroup={<ButtonGroup />}>
    <ItemOne>
    <ItemTwo>
  </Carousel>
</div>

Custom dots.

You can pass your own custom dots to replace the default one.

Custom dots can also be a copy or an image of your carousel item. See example in this one

The codes for this example

You custom dots will receive a list of props/state that's passed back by the carousel such as the currentSide, is dragging or swiping in progress.

Code

const CustomDot = ({ onClick, ...rest }) => {
  const {
    onMove,
    index,
    active,
    carouselState: { currentSlide, deviceType }
  } = rest;
  const carouselItems = [CarouselItem1, CaourselItem2, CarouselItem3];
  // onMove means if dragging or swiping in progress.
  // active is provided by this lib for checking if the item is active or not.
  return (
    <button
      className={active ? "active" : "inactive"}
      onClick={() => onClick()}
    >
      {React.Children.toArray(carouselItems)[index]}
    </button>
  );
};
<Carousel showDots customDot={<CustomDot />}>
  {carouselItems}
</Carousel>;

renderDotsOutside

Passing this props would render the dots outside of the Carousel container. This is done using React.fragment

<div className='my-own-custom-container'>
  <Carousel arrows={false} showDots={true} renderDotsOutside={renderButtonGroupOutside}>
    <ItemOne>
    <ItemTwo>
  </Carousel>
</div>

partialVisible props.

Shows the next items partially, this is very useful if you want to indicate to the users that this carousel component is swipable, has more items behind it.

This is different from the "centerMode" prop, as it only shows the next items. For the centerMode, it shows both.

const responsive = {
  desktop: {
    breakpoint: { max: 3000, min: 1024 },
    items: 3,
    partialVisibilityGutter: 40 // this is needed to tell the amount of px that should be visible.
  },
  tablet: {
    breakpoint: { max: 1024, min: 464 },
    items: 2,
    partialVisibilityGutter: 30 // this is needed to tell the amount of px that should be visible.
  },
  mobile: {
    breakpoint: { max: 464, min: 0 },
    items: 1,
    partialVisibilityGutter: 30 // this is needed to tell the amount of px that should be visible.
  }
}
<Carousel partialVisible={true} responsive={responsive}>
  <ItemOne />
  <ItemTwo />
</Carousel>

centerMode

Shows the next items and previous items partially.

<Carousel centerMode={true} />

afterChange callback.

This is a callback function that is invoked each time when there has been a sliding.

<Carousel
  afterChange={(previousSlide, { currentSlide, onMove }) => {
    doSpeicalThing();
  }}
/>

beforeChange call back

This is a callback function that is invoked each time before a sliding.

<Carousel
  beforeChange={(nextSlide, { currentSlide, onMove }) => {
    doSpeicalThing();
  }}
/>

Combine beforeChange and nextChange, real usage.

They are very useful in the following cases:

• The carousel item is clickable, but you don't want it to be clickable while the user is dragging it or swiping it.

<Carousel
  beforeChange={() => this.setState({ isMoving: true })}
  afterChange={() => this.setState({ isMoving: false })}
>
  <a
    onClick={e => {
      if (this.state.isMoving) {
        e.preventDefault();
      }
    }}
    href="https://w3js.com"
  >
    Click me
  </a>
</Carousel>

• Preparing for the next slide.

<Carousel beforeChange={nextSlide => this.setState({ nextSlide: nextSlide })}>
  <div>Initial slide</div>
  <div
    onClick={() => {
      if (this.state.nextSlide === 1) {
        doVerySpecialThing();
      }
    }}
  >
    Second slide
  </div>
</Carousel>

Skipping callbacks

When calling the goToSlide function on a Carousel the callbacks will be run by default. You can skip all or individul callbacks by passing a second parameter to goToSlide.

this.Carousel.goToSlide(1, true); // Skips both beforeChange and afterChange
this.Carousel.goToSlide(1, { skipBeforeChange: true }); // Skips only beforeChange
this.Carousel.goToSlide(1, { skipAfterChange: true }); // Skips only afterChange

focusOnSelect

Go to slide on click and make the slide a current slide.

<Carousel focusOnSelect={true} />

Using ref.

<Carousel ref={(el) => (this.Carousel = el)} arrows={false} responsive={responsive}>
  <ItemOne />
  <ItemTwo />
</Carousel>
<button onClick={() => {
    const nextSlide = this.Carousel.state.currentSlide + 1;
     // this.Carousel.next()
     // this.Carousel.goToSlide(nextSlide)
  }}>Click me</button>

additionalTransfrom Props.

This is very useful when you are fully customizing the control functionality by yourself like this one

Code

For example if you give to your carousel item padding left and padding right 20px. And you have 5 items in total, you might want to do the following:

<Carousel ref={el => (this.Carousel = el)} additionalTransfrom={-20 * 5} /> // it needs to be a negative number

Specific Props

Author

👤 Yi Zhuang

• Github: @YIZHUANG

🤝 Contribute

Please read https://github.com/YIZHUANG/react-multi-carousel/blob/master/contributing.md

Submit an issue for feature request or submit a pr.

Local development.

• cd app
• npm install
• npm run dev

Donation

If this project help you reduce time to develop, you can give me a cup of coffee :)

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Truong Hoang Dung 💻	Tobias Pinnekamp 💻	Rajendran Nadar 💻	Abhinav Dalal 💻	Oscar Barrett 💻	Neamat Mim 💻	Martin Retrou 💻
Ben Hodgson 💻	Faizan ul haq 💻	Adrian3PG 💻	kuznetsovgm 💻	Vadim Filimonov 📖	Romain 💻	Riley Lundquist 💻
Paul Deshaies Jr 💻	Pavel Mikheev 💻	nev1d 💻	Mads Vammen 💻	Jiro Farah 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

All notable changes to this project will be documented in this file. Dates are displayed in UTC.

Generated by auto-changelog.

v2.8.1

14 June 2022

• Added RTL support and fixed autoPlay being enabled by accident #349
• Fixed autoPlaySpeed type and disabled animation for rewind #337
• docs: add MaSchVam as a contributor for code #336
• Added "Rewind" option #334
• docs: add nev1d as a contributor for code #321
• feat(shouldResetAutoplay): Ability to reset autoplay interval after slide change #264
• docs: add donotcodeit as a contributor for code #320
• docs: add ak-pdeshaies as a contributor for code #319
• ISSUE #296 - Change item to go to when reaching the start of the item list #316
• feat(pauseOnHover): change pauseOnHover logic #263
• docs: add rlundquist3 as a contributor #254
• Added Fix for using tab to slide through the carousel list #252
• Visible disabled arrows with disabled attribute #225
• pauseOnHover property #246
• adding a functionality for remote adding aria label on the li #231
• docs: add groomain as a contributor #221
• Remove partialVisibilityGutter when totalItems is equal to slidesToShow #218
• docs: add VadimFilimonov as a contributor #220
• docs: add kuznetsovgm as a contributor #219
• Fix readme formatting #209
• Added button type for ArrowButton #206
• Clear items to show resize timeout when component unmounts (Issue #87) #198
• README typo fix #169
• fix(docs): edited typos in the documentation #164
• Activating Open Collective #159
• docs: add Adrian3PG as a contributor #147
• Add RTL Support aa0efcd
• Test RTL direction 787ce7c
• Added sponsor 65af8c6

2.5.4

1 April 2020

• Fix partialVisibilityGutter when showing more than one slide #142
• Include aria-label on dots #144

2.5.3

15 March 2020

• removed resetCurrentSlide true from resize and added a test for the same #138
• docs: add mfaizan1 as a contributor #137
• updated CustomRightArrow useage documentation #136
• [Snyk] Fix for 1 vulnerabilities #126
• fix: examples/ssr/package.json & examples/ssr/package-lock.json to reduce vulnerabilities f62b9d5
• docs: update README.md [skip ci] abc6932
• Fixed documentation url f974b76

2.5.0

18 December 2019

• [Snyk] Fix for 1 vulnerabilities #116
• [Snyk] Fix for 1 vulnerabilities #117
• Remove partialVisibilityGutter when there is not enough children #111
• added :active psuedo class to botton along with hover #118
• [Snyk] Fix for 1 vulnerabilities #113
• fix: app/package.json & app/package-lock.json to reduce vulnerabilities e2dcb07
• fix: app/package.json, app/package-lock.json & app/.snyk to reduce vulnerabilities e6fb07b
• fix: examples/ssr/package.json, examples/ssr/package-lock.json & examples/ssr/.snyk to reduce vulnerabilities efbc527

2.4.2

18 November 2019

• Fixed last pr has incorrect call order to disable dot when there is n… #107
• docs: add benhodgson87 as a contributor #105
• Fixed last pr has incorrect call order to disable dot when there is not enough children 0ad75c5
• docs: update .all-contributorsrc a129c0a
• docs: update README.md ea5e882

2.4.1

18 November 2019

• [#103] Do not render default dots if only one slide #104
• resetTotalItems on children changes #102
• reverted to old changes from PR#71 #101
• Add prop + logic to allow removing dots if only one slide f63263c
• Remove prop, make hiding dots default behaviour 4ed3f77
• Use notEnoughChildren helper for dot count check f1ecc55

2.4.0

30 October 2019

• fixed typo keeping backward compatibility #93
• Improve performance for mouse/touch moving the Carousel. #89
• configure husky #76
• Improve performance by manipulating dom directly 4ca7029
• Fixed test 6ecd08c
• Update .eslintrc.js 8629961

2.3.0

16 October 2019

• docs: add Martinretrou as a contributor #86
• Add aria-label to arrows buttons #85
• docs: add neamatmim as a contributor #84
• docs: add OscarBarrett as a contributor #83
• docs: add abhinavdalal-iconnect as a contributor #82
• docs: add raajnadar as a contributor #81
• docs: add tpinne as a contributor #79
• docs: add revskill10 as a contributor #78
• Added option to skip callbacks #75
• Migrate to eslint #69
• clean up code #68
• [Snyk] Fix for 1 vulnerabilities #67
• [Snyk] Fix for 1 vulnerabilities #66
• setup eslint 0f7c34c
• fix: examples/ssr/package.json, examples/ssr/package-lock.json & examples/ssr/.snyk to reduce vulnerabilities fa5bcfc
• fix: app/package.json, app/package-lock.json & app/.snyk to reduce vulnerabilities b8c36a3

2.2.7

2 October 2019

• clones = children if children.length < slidesToShow #64
• Fixed className undefined and Doc improvement 302d216
• Improve unit test and allow button group to be render outside 4014721
• Changed type namings 3d0e0a9

2.2.4

18 August 2019

• Fixed typo for paritialVisibilityGutter #55
• remove useless next config #52
• Update package-lock.json 9995c82
• Update dependencies 9804b29
• Fixed typings and turn mangle to false for code transformation 6453f87

2.2.2

28 July 2019

• Fixed deployment gets run in PR #51
• Feature/move clones to render method #50
• Fixed test 3737028
• Move clones to render method e865fab
• Update documentation 896a343

v2.1.4

26 July 2019

v2.1.3

26 July 2019

• Fixed deployment pipeline #47

v2.1.2

20 July 2019

• Updates types.ts to provide typings for ref usage #45
• Fixed CI #46
• Bump lodash from 4.17.11 to 4.17.14 #43
• Added more typings 2b2f9dc

v2.1.1

12 July 2019

• [Feature] Basic styled components support #42
• Fetch upstream #1
• Add basic support for styled-components b3cfeba

v2.1.0

8 July 2019

• Update documentation of for the renderDotsOutside props #41
• Adds new option renderDotsOutside #40

v2.0.1

7 July 2019

• Update documentation efdd223
• Update ssr demo d8f3b6c
• Update documentation 97758f5

v2.0.0

6 July 2019

• Added documentation and fix test #39
• New dots mode that behaves exactly the same as react-slick but better. #33
• [Snyk] Fix for 1 vulnerable dependencies #38
• [Snyk] Fix for 1 vulnerable dependencies #37
• [Snyk] Fix for 1 vulnerable dependencies #36
• Added pipeline for documentation #34
• Change a different way of minifying the codes #30
• Added more badges #29
• Update changelog, readme and documentation #27
• fix: examples/ssr/.snyk, examples/ssr/package.json & examples/ssr/package-lock.json to reduce vulnerabilities df9f5be
• fix: app/.snyk, app/package.json & app/package-lock.json to reduce vulnerabilities 7a915da
• Complete dot mode with new calculation a0aa17f

1.4.5

19 June 2019

• Fix CustomDot component's react key warning #26
• Fixed test 1f96f7e
• Reduce one extra re-rendering 617d200
• Change slideIndex to index 49a4de6

1.4.3

9 June 2019

• Clean up codes 0291122
• Update changelog f604fef
• Prevent rendering carousel items on client side before dom is ready dbb24d1

1.4.2

5 June 2019

• Disable drag and and hide arrows as well as set clones when children … #22
• [Snyk] Fix for 1 vulnerable dependencies #20
• Added broswerstack support #18
• Added active className for carousel Item when its in view port 624961b
• Update local development dependencies a959774
• Update ssr examples 3bc2590

1.4.0

11 May 2019

• Minify the codes 408d4d9
• Put uglify-js back in dev dependency da3363d
• Change naming of lastPosition to lastX fc0d144

1.3.21

8 May 2019

• Improve npm search ranking #17
• Added Changelog and License #16
• Add license scan report and status #15
• Put coverage folders back a7cc73e
• Added Dependancy check 356b22f
• Added TROUBLESHOOTING and Tslint 0166503

1.3.18

30 April 2019

• Remove dist files and coverage from git 127be39
• Improve test ab156cb
• Added scrollbar as an example 2279998

1.3.16

26 April 2019

• Remove gutter when reaching the end of slides in non-infinite mode b16a1d0
• Fixed typoes in Readme 6ca29a2

1.3.14

24 April 2019

• Fixed flickering issues on safari eb2dbeb

1.3.13

24 April 2019

• Pre-clone and pre-swtich the carousel items by one for smoother anima… #12
• Pre-clone and pre-swtich the carousel items by one for smoother animation for the infinite mode 3ff25ee
• Update storybooke examples 486302e
• Smoother example for the autoplay example 3012981

1.3.10

16 April 2019

• Make types option because of React.cloneElement 8704ba0

1.3.9

16 April 2019

• Unit test a9ff604
• Added TypeScript usage instruction 802f794
• Change naming of functions to better ones 9e19e38

1.3.7

13 April 2019

• Added center mode functionality #11
• Update storybook 1c076cf
• Update readme af8109b
• Fixed contributing guide 1cf955f

1.3.6

11 April 2019

• Added focusOnSelect props 408f780

1.3.5

8 April 2019

• Testing #9
• Prettify code block #8
• Update storybook b261970
• Added prettier 3c10adb
• Added visibile and active props to carousel items 9d9db63

1.3.0

5 April 2019

• Added support for IE11 and IE10 #7
• Update examples 53b59cc
• Fixed test 19f3508
• Fixed custom dot index should be the original ones 99d7e81

1.2.4

26 March 2019

• Make Infinite mode the same as other common Carousel libs. #5
• Update readme change naming #4
• first commit f546564
• Now everything works nicely a846582
• Added index.js 5acbd12