nuka-carousel

A Pure ReactJS Carousel Component

Install

To add nuka-carousel to your project run the following command in your project folder.

$ yarn add nuka-carousel

OR

$ npm install nuka-carousel

Example

import React from 'react';
import Carousel from 'nuka-carousel';

export default class extends React.Component {
  render() {
    return (
      <Carousel>
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide1" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide2" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide3" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide4" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide5" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide6" />
      </Carousel>
    );
  }
}

Running demo locally

The demo can be launched on your local machine via webpack-dev-server. Once you have cloned this repo locally, run the following:

yarn
yarn build
yarn start

You can access the application on your localhost at the following url: Local Demo

Or on CodeSandBox:

Running Storybook

Once you have cloned this repo locally, run the following to launch Storybook:

yarn
yarn storybook

You can access Storybook on your localhost at the following url: Storybook

Keyboard Controls

• Keyboard shortcuts are disabled as a default. To enable them set enableKeyboardControls prop to true.
• keyCodeConfig prop can be used to configure the default keyCodes

Props

render*Controls

React.PropTypes.func

A set of eight render props for rendering controls in different positions around the carousel.

• Valid render props for the eight positions are renderTopLeftControls, renderTopCenterControls, renderTopRightControls, renderCenterLeftControls, renderCenterCenterControls, renderCenterRightControls, renderBottomLeftControls, renderBottomCenterControls, and renderBottomRightControls.

• The default props are set as renderCenterLeftControls for Previous button, renderCenterRightControls for the Next button and renderBottomCenterControls for the "Paging dots". To change the position or remove "Paging dots", the default positions need to be disabled by setting them to null.

<Carousel
  renderTopCenterControls={({ currentSlide }) => (
    <div>Slide: {currentSlide}</div>
  )}
  renderCenterLeftControls={({ previousSlide }) => (
    <button onClick={previousSlide}>Previous</button>
  )}
  renderCenterRightControls={({ nextSlide }) => (
    <button onClick={nextSlide}>Next</button>
  )}
>
  {/* Carousel Content */}
</Carousel>

• The function returns the props for goToSlide, nextSlide and previousSlide functions, in addition to slideCount and currentSlide values. You can also remove all render controls using withoutControls.

• NOTE: The className slide-visible is added to the currently visible slide or slides (when slidesToShow > 1). The className slide-current is added to the currently "active" slide.

renderAnnounceSlideMessage

React.PropTypes.func

renderAnnounceSlideMessage render prop is a special case of the render*Controls props. It's responsibility is to render ARIA live announcement message to improve accessibility. The prop will announce the message you pass in every time the slide changes with VoiceOver enabled on your machine. The function returns only slideCount and currentSlide values.

<Carousel
  renderAnnounceSlideMessage={({ currentSlide, slideCount }) =>
    `Slide ${currentSlide + 1} of ${slideCount}`
  }
>
  {/* Carousel Content */}
</Carousel>

getControlsContainerStyles

React.PropTypes.func

getControlsContainerStyles is a function prop that will be called with a key argument being one of the following: TopLeft | TopCenter | TopRight | CenterLeft | CenterCenter | CenterRight | BottomLeft | BottomCenter | BottomRight. The function will then return CSS Properties.

<Carousel
  getControlsContainerStyles={(key) => {
     switch (key) {
        case 'TopLeft':
          return {
            backgroundColor: "red",
          };
        default:
          // will apply all other keys
          return {
            backgroundColor: "blue",
          };
      }
  }} />
>
  {/* Carousel Content */}
</Carousel>

defaultControlsConfig

React.PropTypes.shape({
  nextButtonClassName: PropTypes.string,
  nextButtonStyle: PropTypes.object,
  nextButtonText: PropTypes.string,
  prevButtonClassName: PropTypes.string,
  prevButtonStyle: PropTypes.object,
  prevButtonText: PropTypes.string,
  pagingDotsContainerClassName: PropTypes.string,
  pagingDotsClassName: PropTypes.string,
  pagingDotsStyle: PropTypes.object
})

The default controls used by Nuka are the Previous button, Next button, and PagingDots control. The visual look and text of these controls can be modified with props as described below:

• The props ending with ClassName let you apply a custom css class to its respective control.
• The props ending with Style let you apply inline styles to its respective control.
• The text label for the Previous button and Next button can be customized using prevButtonText and nextButtonText, respectively.

For example, you can change the text of the Previous and Next buttons, and change the paging dots to red by passing in the following configuration:

defaultControlsConfig={{
  nextButtonText: 'Custom Next',
  prevButtonText: 'Custom Prev',
  pagingDotsStyle: {
    fill: 'red'
  }
}}

External Control of Carousel State

You can control the state of the carousel from your parent component as shown below:

import React from 'react';
import Carousel from 'nuka-carousel';

export default class extends React.Component {
  state = {
    slideIndex: 0
  };

  render() {
    return (
      <Carousel
        slideIndex={this.state.slideIndex}
        afterSlide={(slideIndex) => this.setState({ slideIndex })}
      >
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide1" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide2" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide3" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide4" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide5" />
        <img src="https://via.placeholder.com/400/ffffff/c0392b/&text=slide6" />
      </Carousel>
    );
  }
}

TypeScript

TypeScript type definitions are now shipped with nuka-carousel. You can use them directly from the library.

Resizing Height

How resizing works

In componentDidMount, the initial dimensions are assigned to each slide:

• Width: initialSlideWidth || slideWidth || (slidesToShow / width of container)
• Height: initialSlideHeight

After the component completes mounting with the accurate width, it tries to calculate the desired height of the content (current, first, max). If that calculation fails (perhaps because slide images are still loading), it'll wait a bit and try again. Once successful, that measurement then replaces initialSlideHeight with the measured height in pixels.

Contributing

See the Contribution Docs.

Maintenance Status

Active: Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.