Skip to main content

API

Props for the <Carousel /> component with their types and default values.

adaptiveHeight​

A boolean to set the carousel to adapt its height to the visible slides. Default value: false.

adaptiveHeightAnimation​

A boolean to animate height changes when adaptiveHeight is enabled. Default value: false.

afterSlide​

A function (index: number) => void to be called after a slide is changed with a slide index parameter.

autoplay​

A boolean to set the carousel to automatically play through the slides. Default value: false.

autoplayInterval​

A number for the autoplay iteration in milliseconds. Default value: 3000.

beforeSlide​

A function (index: number) => void to be called before a slide is changed with a slide index parameter.

carouselId​

A string prop that gives the carousel frame an id attribute which can be uniquely targeted by controls. This prevents collisions if there are multiple instances of Nuka in a single tree. The default value is generated by React’s useId hook.

cellAlign​

An enum 'left' | 'center' | 'right' for when displaying more than one slide, sets which position to anchor the current slide. Default value: 'left'.

cellSpacing​

A number representing pixels for the spacing between slides. Default value: 0.

className​

A string for the CSS selectors to be applied to the slider frame.

defaultControlsConfig​

A configuration object to apply custom classes and styles to the default controls. Learn more about the interface.

disableAnimation​

A boolean to disable the animation of the carousel. Default value: false.

disableEdgeSwiping​

A boolean to disable swiping past the edge for the first and last slides. Default value: false.

dragging​

A boolean to enable dragging of slides to navigate using a pointing device. Default value: true.

dragThreshold​

A number representing the percentage (from 0 to 1) of a slide that the user needs to drag before a slide change is triggered. Default value: 0.5.

easing​

An easing function (normalizedTime: number) => number for the navigation animations. Learn more about how to use the easing function. The default function is a cubic ease out.

edgeEasing​

An easing function (normalizedTime: number) => number for when the navigation exceeds the edge. Learn more about how to use the easing function. The default function is a cubic ease out.

enableKeyboardControls​

A boolean to enable keyboard controls when the carousel has focus. If the carousel does not have focus, keyboard controls will be ignored. Default value: false.

frameAriaLabel​

A string for the aria-label of the frame container of the carousel. This is useful when you have more than one carousel on the page. The default value is now Slider, this is changed from v6 and earlier.

keyCodeConfig​

A configuration object for the key codes to override the default keyboard keys configured when enableKeyboardControls is true. Learn more about the interface.

landmark​

A boolean that determines whether role should be a region landmark or have role group. Role and label have been moved from the slider frame to the parent carousel element so controls are contained within the label and role. Landmark regions should be intentional, so the default value is set to false.

onDragStart​

A function (e: React.TouchEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>) => void; to capture event at the start of swiping and dragging slides.

onDrag​

A function (e: React.TouchEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>) => void; to capture the dragging and swiping events on slides.

onDragEnd​

A function (e: React.TouchEvent<HTMLDivElement> | React.MouseEvent<HTMLDivElement>) => void; to capture event at the end of swiping and dragging slides.

onUserNavigation​

A function (e: React.TouchEvent | React.MouseEvent | React.KeyboardEvent) => void; to capture user-triggered when navigation occurs: dragging and swiping, clicking one of the controls (custom controls not included), or using a keyboard shortcut.

pauseOnHover​

A boolean to autoplay when mouse hovered over the carousel. Default value is true.

onUserNavigation​

A function (props: Pick<CarouselState, 'currentSlide' | 'count'>) => string to render the message in the ARIA live region that is announcing the current slide on slide change.

ref​

A React ref object MutableRefObject<HTMLDivElement | null> for carousel element.

renderTopLeftControls​

A function to render custom controls for the top left area of the carousel. Learn more about function and the parameters it accepts.

renderTopCenterControls​

A function to render custom controls for the top center area of the carousel. Learn more about function and the parameters it accepts.

renderTopRightControls​

A function to render custom controls for the top right area of the carousel. Learn more about function and the parameters it accepts.

renderCenterLeftControls​

A function to render custom controls for the center left area of the carousel. Learn more about function and the parameters it accepts.

renderCenterCenterControls​

A function to render custom controls for the center middle area of the carousel. Learn more about function and the parameters it accepts.

renderCenterRightControls​

A function to render custom controls for the center right area of the carousel. Learn more about function and the parameters it accepts.

renderBottomLeftControls​

A function to render custom controls for the bottom left area of the carousel. Learn more about function and the parameters it accepts.

renderBottomCenterControls​

A function to render custom controls for the bottom center area of the carousel. Learn more about function and the parameters it accepts.

renderBottomRightControls​

A function to render custom controls for the bottom right area of the carousel. Learn more about function and the parameters it accepts.

scrollMode​

An enum 'page' | 'remainder' for showing whitespace when you scroll to the end of a carousel with wrapAround set to false. Setting to 'remainder' will not show the whitespace. Default value: 'page'.

slideIndex​

A number to set the index of the slide to be shown. This value is unset by default.

slidesToScroll​

A number to set the amount of slides to scroll at once. This prop is ignored when animation is set to fade. Default value is 1.

slidesToShow​

A number to set the amount of slides to show at once. This prop is will be cast as an integer when animation is set to fade since fractional slides are not supported with that animation type. Default value is 1.

speed​

A number to set the animation duration and transition speed in milliseconds. Default value is 500.

style​

A CSSProperties object to set additional inline styles for the carousel frame.

swiping​

A boolean to enable touch swipe and dragging for navigation. Default value is true.

tabbed​

A boolean which enables the tabpannel aria role for the carousel to conform to WCAG tabbed carousel requirements. Default value is true.

withoutControls​

A boolean to remove and hide all controls. Default value is false.

wrapAround​

A boolean to enable wrap around mode where the carousel can infinitely navigate forwards and backwards. Default value is false.

zoomScale​

A number to set the scale of zoom when the animation type is set to zoom. The number should range from 0 to 1. Default value is 0.85.

Default Controls Configuration​

A configuration object to apply custom classes and styles to the default container, navigation buttons, and progress dot controls. This configuration object also lets you add additional event handlers to each of the navigation item's click handlers.

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

}

Control Render Functions​

The control render functions are render props that let you provide a custom UI that overrides the default UI for each of the control areas. The signature for the render functions is: (props: ControlProps) => JSX.Element.

interface ControlProps {
  currentSlide: number;
  slideCount: number;
  pagingDotsIndices: number[];
  nextDisabled: boolean;
  previousDisabled: boolean;
  nextSlide(): void;
  previousSlide(): void;
  goToSlide(targetIndex: number): void;
}

currentSlide​

A number set to the current slide index.

slideCount​

A number set to the number of slides.

pagingDotsIndices​

An array number[] set the indexes of the active slides.

nextDisabled​

A boolean indicating if a custom next slide control be disabled

previousDisabled​

A boolean indicating if a custom next slide control be disabled

nextSlide​

A function to invoke to navigate to the next slide.

previousSlide​

A function to invoke to navigate to the previous slide.

goToSlide​

A function to invoke with a number parameter to navigate to a specific slide.

Key Code Configuration​

A configuration object for the key codes to override the default keyboard keys configured when enableKeyboardControls is true. Multiple custom key codes can be provided for each action.

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

Easing Functions​

(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.