DOCSEARCHbyAlgolia
Submit Docs

nuka-carousel

repository·main·Indexed 25 days ago

https://github.com/formidablelabs/nuka-carousel

A small, fast, and accessibility-first React carousel library. It features a highly customizable UI and behavior, supporting features such as autoplay, adaptive height, keyboard navigation, and custom easing functions. The library provides a <Carousel /> component with a comprehensive API for managing navigation arrows, paging dots, wrapping behavior, and slide events, and requires React 18 as a peer dependency.

Tokens
7.6K
Snippets
25
Records
55
Agent score
85%

What's inside nuka-carousel

  2. Migrate Changed Props in Nuka v8

    main

    The following props have changed their names or signatures in v8. Update your implementation to use the new equivalents:

    • carouselId $\rightarrow$ Use id instead.
    • slidesToScroll $\rightarrow$ Renamed to scrollDistance.
    • frameAriaLabel $\rightarrow$ Replaced by the title prop.
    • afterSlide and beforeSlide $\rightarrow$ The API signatures have changed. Refer to the callbacks documentation for the new signature.
    • disableAnimation $\rightarrow$ Use the autoPlay property (see navigation docs).
    • dragging $\rightarrow$ Now enabled by default. Use the swiping property to control this.
    • enableKeyboardControls $\rightarrow$ Now enabled by default. Use the keyboard property to control this.

  3. Use HTML block elements in the Carousel

    main

    When using HTML block elements like <div> as slides, you must set a min-width in your CSS or inline styles so that Nuka can correctly measure the slide dimensions.

    /* CSS */
.demo-slide {
  min-width: 300px;
  min-height: 100px;
}

/* JSX */
<Carousel showDots>
  <div className="demo-slide bg-green-500" />
  <div className="demo-slide bg-red-500" />
  <div className="demo-slide bg-blue-500" />
</Carousel>

  6. Use images in the Carousel

    main

    Nuka will automatically calculate the width and height of images after they load. However, to prevent layout shifts and ensure compatibility with frameworks like Next/image, it is recommended to explicitly set the width and height attributes on your <img> tags.

    <Carousel showDots>
  <img src="pexels-01.jpg" width={300} height={100} />
  <img src="pexels-02.jpg" width={300} height={100} />
  <img src="pexels-03.jpg" width={300} height={100} />
</Carousel>

  8. Handle Removed Props in Nuka v8

    main

    The following props have been removed in v8. You must adjust your configuration to accommodate these changes:

    Automatic Functionality (No prop needed)

    • adaptiveHeight and adaptiveHeightAnimation: The carousel now adapts to item height automatically.
    • pauseOnHover: Enabled by default. Use autoPlay settings to manage this.
    • tabbed: Enabled by default.
    • slidesToShow: Now determined by media queries and slide size.
    • speed: Controlled by native browser settings.
    • dragThreshold: Defaults to OS/browser settings.

    Replaced by Other Props or Methods

    • slideIndex: Use initialPage to set the starting page, or the goToPage method to change indices programmatically.
    • defaultControlsConfig and withoutControls: Replaced by individual properties like showArrows, showDots, arrows, and dots.
    • style, cellAlign, and cellSpacing: These are now controlled via CSS.

    Removed (No direct replacement listed)

    • disableEdgeSwiping
    • easing
    • edgeEasing
    • keyCodeConfig
    • landmark
    • onDragStart, onDrag, and onDragEnd
    • onUserNavigation
    • render{position}{direction}Controls
    • scrollMode (defaults to remainder)
    • zoomScale
    • zoomScale

  11. Customize Default Controls

    main

    Use the defaultControlsConfig prop to apply custom CSS classes, inline styles, or text to the default navigation buttons and paging dots. You can also attach custom onClick handlers to these elements.

    interface DefaultControlsConfig  {
  containerClassName?: string
  nextButtonClassName?: string
  nextButtonStyle?: CSSProperties
  nextButtonText?: React.ReactNode
  pagingDotsClassName?: string
  pagingDotsContainerClassName?: string
  pagingDotsStyle?: CSSProperties
  prevButtonClassName?: string
  prevButtonStyle?: CSSProperties
  prevButtonText?: React.ReactNode
  prevButtonOnClick?(event: React.MouseEvent): void
  nextButtonOnClick?(event: React.MouseEvent): void
  pagingDotsOnClick?(event: React.MouseEvent): void
}

  12. Configure Keyboard Controls and Key Codes

    main

    To enable keyboard navigation, set enableKeyboardControls to true. You can further customize which keys trigger specific actions using the keyCodeConfig prop.

    interface KeyCodeConfig {
  firstSlide?: number[];
  lastSlide?: number[];
  nextSlide?: number[];
  pause?: number[];
  previousSlide?: number[];
}