API (v7)
Carousel Props
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.