Natty Precise Maverick

    nuka-carousel
    TypeScript icon, indicating that this package has built-in type declarations

    5.4.1 • Public • Published

    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

    Name Type Description Default
    adaptiveHeight boolean If it's set to true, the carousel will adapt its height to the visible slides. false
    adaptiveHeightAnimation boolean Whether to animate height changes when adaptiveHeight is enabled true
    afterSlide (index: number) => void Hook 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.
    autoplay boolean Autoplay mode active. false
    autoplayInterval number Interval for autoplay iteration in milliseconds. 3000
    autoplayReverse boolean Only 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) => void Hook 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
    cellSpacing number Space between slides, as an integer, but reflected as px 0
    className string Slider frame class name ''
    defaultControlsConfig
    interface DefaultControlsConfig  { 
     containerClassName?: string; 
     nextButtonClassName?: string; 
     nextButtonOnClick?: (event: React.MouseEvent) => void; 
     nextButtonStyle?: CSSProperties; 
     nextButtonText?: React.ReactNode; 
     pagingDotsClassName?: string; 
     pagingDotsContainerClassName?: string; 
     pagingDotsOnClick?: (event: React.MouseEvent) => void; 
     pagingDotsStyle?: CSSProperties; 
     prevButtonClassName?: string; 
     prevButtonOnClick?: (event: React.MouseEvent) => void; 
     prevButtonStyle?: CSSProperties; 
     prevButtonText?: React.ReactNode; 
    }
    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 in the defaultControlsConfig section. {}
    disableAnimation boolean When set to true, will disable animation. false
    disableEdgeSwiping boolean When set to true, will disable swiping before first slide and after last slide. false
    dragging boolean Enable mouse swipe/dragging. true
    dragThreshold number The percentage (from 0 to 1) of a slide that the user needs to drag before a slide change is triggered. 0.5
    easing (normalizedTime: number) => number Animation easing function. See the Easing section for more details A cubic easeOut function
    edgeEasing (normalizedTime: number) => number Animation easing function when swipe exceeds edge. See the Easing section for more details A cubic easeOut function
    enableKeyboardControls boolean When 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
    frameAriaLabel string Customize the aria-label of the frame container of the carousel. This is useful when you have more than one carousel on the page. ''
    innerRef MutableRefObject<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 end of swiping/dragging slides
    onUserNavigation (e: React.TouchEvent | React.MouseEvent | React.KeyboardEvent) => void; Callback called when user-triggered navigation occurs: dragging/swiping, clicking one of the controls (custom controls not included), or using a keyboard shortcut
    pauseOnHover boolean Pause autoPlay when mouse is over carousel. true
    renderAnnounceSlideMessage (props: Pick<CarouselState, 'currentSlide' | 'count'>) => string Renders message in the ARIA live region that is announcing the current slide on slide change Render 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'
    slideIndex number Manually set the index of the slide to be shown
    slidesToScroll number Slides to scroll at once. The property is overridden to slidesToShow when animation="fade" 1
    slidesToShow number Number of slides to show at once. Will be cast to an integer when animation="fade" 1
    speed number Animation duration/Transition speed in milliseconds 500
    style CSSProperties Add inline style to the carousel frame {}
    swiping boolean Enable touch swipe/dragging true
    withoutControls boolean Used to remove all controls at once. Overwrites the render[Top, Right, Bottom, Left]CenterControls(). false
    wrapAround boolean Sets infinite wrapAround mode. An option similar to repeat or infinite in other libs. false
    zoomScale number Adds 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.

    • You can remove all render controls using the withoutControls prop on Carousel.

    • The render functions receive a ControlProps argument containing the following props from the Carousel props, using default values if not originally defined:

      cellAlign
      cellSpacing
      defaultControlsConfig
      onUserNavigation
      scrollMode
      slidesToScroll
      slidesToShow
      wrapAround
      

      Additionally, the following data and callbacks are provided to make creating controls easier:

      Name Type Description
      currentSlide number Current slide index
      pagingDotsIndices number[] The indices for the paging dots
      goToSlide (targetIndex: number) => void Go to a specific slide
      nextDisabled boolean Whether the "next" button should be disabled or not
      nextSlide () => void Go to the next slide
      previousDisabled boolean Whether the "previous" button should be disabled or not
      previousSlide () => void Go to the previous slide
      slideCount number Total number of slides

    Example:

    <Carousel
      renderTopCenterControls={({ currentSlide }) => (
        <div>Slide: {currentSlide}</div>
      )}
      renderCenterLeftControls={({ previousDisabled, previousSlide }) => (
        <button onClick={previousSlide} disabled={previousDisabled}>
          Previous
        </button>
      )}
      renderCenterRightControls={({ nextDisabled, nextSlide }) => (
        <button onClick={nextSlide} disabled={nextDisabled}>
          Next
        </button>
      )}
    >
      {/* Carousel Content */}
    </Carousel>
    • 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.

    easing and edgeEasing

    (normalizedTime: number) => number

    A function accepting a normalized time between 0 and 1, inclusive, and returning an eased time, which equals 0 at normalizedTime==0 and equals 1 at normalizedTime==1. You can plug in your own custom easing function (e.g., (t) => t for a linear transition), or import functions from a different library, like d3-ease.

    import { easeCircleOut, easeElasticOut } from 'd3-ease';
    
    // ...
    
    <Carousel easing={easeCircleOut} edgeEasing={easeElasticOut}>
      {/* Carousel Content */}
    </Carousel>

    Please note that using a function for easing with "In" in it (easeInOut, easeElasticIn, etc.) will make swiping transitions feel a bit clunky, as the velocity at the end of the swipe will suddenly drop to follow the slow startup speed of the "In" easing function. In general, when using custom easing functions, try out both swiping and clicking on the navigation buttons to see how the transitions feel.

    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;
      nextButtonOnClick?: (event: React.MouseEvent) => void;
      nextButtonStyle?: CSSProperties;
      nextButtonText?: React.ReactNode;
      pagingDotsClassName?: string;
      pagingDotsContainerClassName?: string;
      pagingDotsOnClick?: (event: React.MouseEvent) => void;
      pagingDotsStyle?: CSSProperties;
      prevButtonClassName?: string;
      prevButtonOnClick?: (event: React.MouseEvent) => void;
      prevButtonStyle?: CSSProperties;
      prevButtonText?: React.ReactNode;
    }
    

    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 props ending with OnClick let you listen for user interaction with the controls.
    • 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.

    Install

    npm i nuka-carousel

    DownloadsWeekly Downloads

    110,439

    Version

    5.4.1

    License

    MIT

    Unpacked Size

    353 kB

    Total Files

    88

    Last publish

    Collaborators

    • keithluchtel
    • ceceppa
    • robwalkerco
    • gksander
    • sarahformidable
    • scott-rippey
    • yankovalera
    • michaelmerrill
    • sarmeyer
    • mariano-formidable
    • carlospaelinck
    • ryan.roemer
    • formidable-owner
    • eastridge
    • exogen
    • jmcbee1
    • formidablelabs
    • carbonrobot
    • masiddee
    • nuka-carousel-ci
    • thekenwheeler
    • stefvhuynh