nuka-carousel
4.3/53
nuka-carousel
npm i nuka-carousel
nuka-carousel

nuka-carousel

Pure React Carousel Component

by FormidableLabs

5.2.0 (see all)License:MITTypeScript:Built-InCategories:React Swipe, React Carousel
npm i nuka-carousel
Readme

nuka-carousel

Maintenance Status

Small, fast and accessibility-first React carousel library with easily customizable UI and behavior to fit your brand and site

Nuka Carousel Animated Example

If you are looking for v4 documentation, you can find it here

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

Migration guide from v4 to v5 is under development, please raise any questions in the Issues tab of the repository.

Example

You can test nuka-carousel default behaviour. Link

  <Carousel>
    <img src="/image1.png" />
    <img src="/image2.png" />
    <img src="/image3.png" />
    <img src="/image4.png" />
    <img src="/image5.png" />
  </Carousel>

Infinity nuka-carousel@5 with 3 slides to show. Link

  <Carousel
    wrapAround={true}
    slidesToShow={3}
  >
    <img src="/image1.png" />
    <img src="/image2.png" />
    <img src="/image3.png" />
    <img src="/image4.png" />
    <img src="/image5.png" />
  </Carousel> 

You can play with &params url parameter to add or remove any carousel parameters and see how the carousel behaves. We are looking to build a proper documentation page with many examples and code snippets.

Improvements in v5

  • Support server-side rendering. Currently in v4 all of the slides are positioned with position: absolute, which doesn't render the slides appropriately when javascript is disabled and there are flickering when the front-end is hydrated. This forced users to hardcode properties for the carousel like initialSlideHeight and initialSlideWidth. In v5 all slides are positioned with dynamic width, so the slides and carousel can be fully responsive and rendered correctly on server as well.
  • Rewritten the library with TypeScript and React Hooks for obvious reasons.
  • Reduce the size of the library and its dependencies. Currently v4 has 5 dependencies - prop-types, d3-ease, wicg-inert, exenv and react-move. We are looking to use only d3-ease in v5.1, but definitely after bumping the version of it to the latest.
    • prop-types is replaced with usage of TypeScript.
    • exenv is not maintained anymore and is removed with v5 as a dependency of nuka-carousel.
    • wicg-inert doesn't have specified license, so we are going to remove it from our dependencies. More info here. We are still supporting inert and we will have an example and more detailed documentation how you can use it with nuka-carousel v5.
    • react-move nothing personal, we just decided to go for our custom approach of animations in order to reduce the size of the library.
  • Fixed issues. We fixed a lot of the issues that we currently have in v4. You can see the full list with fixed issues in our v5 project. Link

Props

NameTypeDescriptionDefault
adaptiveHeightbooleanIf it's set to true, the carousel will adapt its height to the visible slides.false
adaptiveHeightAnimationbooleanWhether to animate height changes when adaptiveHeight is enabledtrue
afterSlide(index: number) => voidHook to be called after a slide is changed.() => {}
animation'zoom' \| 'fade'Adds a zoom effect on the currently visible slide or change the animation to fade. A transform: scale(0.85) is set as default when you are using zoom, however, the scale can be customized using zoomScale prop. Property is applied on all slides except the current 1. Use cellAlign to align the slide with zoom effect where you'd like.
autoplaybooleanAutoplay mode active.false
autoplayIntervalnumberInterval for autoplay iteration in milliseconds.3000
autoplayReversebooleanOnly meaningful when autoplay is already true. When autoplayReverse is also true, autorotation cycles through slides indexes from high to low.false
beforeSlide(currentSlideIndex: number, endSlideIndex: number) => voidHook to be called before a slide is changed() => {}
cellAlign'left' \| 'center' \| 'right'When displaying more than one slide, sets which position to anchor the current slide to.left
cellSpacingnumberSpace between slides, as an integer, but reflected as px0
classNamestringSlider frame class name''
defaultControlsConfig
interface DefaultControlsConfig  { 
 containerClassName?: string; 
 nextButtonClassName?: string; 
 nextButtonStyle?: CSSProperties; 
 nextButtonText?: string; 
 pagingDotsClassName?: string; 
 pagingDotsContainerClassName?: string; 
 pagingDotsStyle?: CSSProperties; 
 prevButtonClassName?: string; 
 prevButtonStyle?: CSSProperties; 
 prevButtonText?: string; 
}
This prop lets you apply custom classes and styles to the default Container. Next, Previous, and Paging Dots controls. More information on how to customize these controls can be found below.{}
disableAnimationbooleanWhen set to true, will disable animation.false
disableEdgeSwipingbooleanWhen set to true, will disable swiping before first slide and after last slide.false
draggingbooleanEnable mouse swipe/dragging.true
dragThresholdnumberThe percentage (from 0 to 1) of a slide that the user needs to drag before a slide change is triggered.0.5
enableKeyboardControlsbooleanWhen set to true will enable keyboard controls when the carousel has focus. If the carousel does not have focus, keyboard controls will be ignored.false
frameAriaLabelstringCustomize the aria-label of the frame container of the carousel. This is useful when you have more than one carousel on the page.''
innerRefMutableRefObject<HTMLDivElement>React ref that should be set on the carousel element
keyCodeConfig
interface KeyCodeConfig { 
  firstSlide?: number[]; 
  lastSlide?: number[];
  nextSlide?: number[]; 
  pause?: number[]; 
  previousSlide?: number[]; 
}
If enableKeyboardControls prop is true, you can pass configuration for the keyCode so you can override the default keyboard keys configured.{ nextSlide: [39, 68, 38, 87], previousSlide: [37, 65, 40, 83], firstSlide: [81], lastSlide: [69], pause: [32] }
onDragStart(e?: React.TouchEvent<HTMLDivElement> \| React.MouseEvent<HTMLDivElement>) => void;Adds a callback to capture event at the start of swiping/dragging slides
onDrag(e?: React.TouchEvent<HTMLDivElement> \| React.MouseEvent<HTMLDivElement>) => void;Adds a callback to capture swiping/dragging event on slides
onDragEnd(e?: React.TouchEvent<HTMLDivElement> \| React.MouseEvent<HTMLDivElement>) => void;Adds a callback to capture event at the ent of swiping/dragging slides
pauseOnHoverbooleanPause autoPlay when mouse is over carousel.true
renderAnnounceSlideMessage(props: Pick<CarouselState, 'currentSlide' \| 'count'>) => stringRenders message in the ARIA live region that is announcing the current slide on slide changeRender function that returns "Slide {currentSlide + 1} of {slideCount}"
scrollMode'page' \| 'remainder'Set scrollMode="remainder" if you don't want to see the white space when you scroll to the end of a non-infinite carousel. scrollMode property is ignored when wrapAround is enabled'page'
slideIndexnumberManually set the index of the slide to be shown
slidesToScrollnumberSlides to scroll at once. The property is overridden to slidesToShow when animation="fade"1
slidesToShownumberNumber of slides to show at once. Will be cast to an integer when animation="fade"1
speednumberAnimation duration/Transition speed in milliseconds500
styleCSSPropertiesAdd inline style to the carousel frame{}
swipingbooleanEnable touch swipe/draggingtrue
withoutControlsbooleanUsed to remove all controls at once. Overwrites the render[Top, Right, Bottom, Left]CenterControls().false
wrapAroundbooleanSets infinite wrapAround mode. An option similar to repeat or infinite in other libs.false
zoomScalenumberAdds a number value to set the scale of zoom when animation === "zoom". The number value should be set in a range of (0,1).0.85

render*Controls

Type: (props: ControlProps) => ReactElement

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

(props: Pick<CarouselState, 'currentSlide' \| 'count'>) => string

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>

defaultControlsConfig

interface DefaultControlsConfig {
  containerClassName?: string;
  nextButtonClassName?: string;
  nextButtonStyle?: CSSProperties;
  nextButtonText?: string;
  pagingDotsClassName?: string;
  pagingDotsContainerClassName?: string;
  pagingDotsStyle?: CSSProperties;
  prevButtonClassName?: string;
  prevButtonStyle?: CSSProperties;
  prevButtonText?: string;
}

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'
  }
}}

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.

Downloads/wk

92.7K

GitHub Stars

2.7K

LAST COMMIT

6mos ago

MAINTAINERS

27

CONTRIBUTORS

121

OPEN ISSUES

33

OPEN PRs

5
VersionTagPublished
5.2.0
latest
22d ago
5.0.5
beta
5mos ago