Carousel API

API documentation for Carousel component

CarouselRoot#

Props#

Defines valid properties in Carousel component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselRootInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselRootInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselRootPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselRootInstance) => ReactNode)	null	The children to render.
autoSize	boolean	false	Whether the carousel should auto size.
orientation	"horizontal" \| "vertical"	'horizontal'	Orientation of the carousel.
align	"center" \| "start" \| "end"	'center'	Alignment of the carousel items.
loop	boolean	false	Whether the carousel should loop.
snapType	"mandatory" \| "proximity"	'mandatory'	Scroll snap type applied to the track.
spacing	number	16	Spacing between carousel items.
slidesPerPage	number	1	How many slides are visible per page. Supports fractions (e.g. 1.5).
page	number	undefined	Index of the active slide.
slide	number	undefined	Index of the active slide.
defaultPage	number	0	Default index of the active slide.
onPageChange	(event: useCarouselChangeEvent) => void	null	Callback fired when the carousel's page changes.
onSlideChange	(event: useCarouselChangeEvent) => void	null	Callback fired when the active slide (by value) changes.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Defines valid state in Carousel component.

name	type	default	description
isPrevDisabled	boolean	null	Whether the "previous" navigation button should be disabled.
isNextDisabled	boolean	null	Whether the "next" navigation button should be disabled.
snapPoints	Set<number>	null	The snap points of the carousel.
page	number	null	The current page of the carousel.
swiping	boolean	null	Whether the user is currently swiping the carousel by touch.

Exposes#

Defines the methods and properties exposed by Carousel component.

name	type	default	description
state	useCarouselState	null	The state of the useCarousel.
contentRef	RefObject<HTMLDivElement>	null	Ref to the content element.
slidesPerPage	number	null	Number of slides displayed per page.
prev	() => void	null	Navigates to the previous slide.
next	() => void	null	Navigates to the next slide.
scrollTo	(value: number) => void	null	Scrolls to the specified value.
scrollToPage	(page: number) => void	null	Scrolls to the specified page.
scrollToSlide	(slide: number) => void	null	Scrolls to the specified slide value.
setToClosest	() => void	null	Scrolls to the closest snap point.
onContentPointerDown	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer down.
onContentPointerMove	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer move.
onContentPointerUp	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer up.
onContentWheel	(event: WheelEvent<HTMLDivElement>) => void	null	Event handler for content wheel.
resolveSnapType	() => string	null	Computes the appropriate CSS `scroll-snap-type` value based on orientation and snapping behavior.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of Carousel component.

name	type	default	description
root	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of Carousel component.

values
ComponentInstance<CarouselRootProps, CarouselRootState, CarouselRootExposes>

CarouselContent#

Props#

Defines valid properties in CarouselContent component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselContentInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselContentInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselContentPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselContentInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselContent component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselContent component.

name	type	default	description
root	CarouselContentPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselContent component.

values
ComponentInstance<CarouselContentProps, CarouselContentState, CarouselContentExposes>

CarouselItem#

Props#

Defines valid properties in CarouselItem component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselItemInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselItemInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselItemPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselItemInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselItem component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselItem component.

name	type	default	description
root	CarouselItemPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselItem component.

values
ComponentInstance<CarouselItemProps, CarouselItemState, CarouselItemExposes>

CarouselIndicators#

Props#

Defines valid properties in CarouselIndicators component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselIndicatorsInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselIndicatorsInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselIndicatorsPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselIndicatorsInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselIndicators component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselIndicators component.

name	type	default	description
root	CarouselIndicatorsPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselIndicators component.

values
ComponentInstance<CarouselIndicatorsProps, CarouselIndicatorsState, CarouselIndicatorsExposes>

CarouselIndicator#

Props#

Defines valid properties in CarouselIndicator component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselIndicatorInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselIndicatorInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselIndicatorPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselIndicatorInstance) => ReactNode)	null	The children to render.
page	number	null
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselIndicator component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselIndicator component.

name	type	default	description
root	CarouselIndicatorPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselIndicator component.

values
ComponentInstance<CarouselIndicatorProps, CarouselIndicatorState, CarouselIndicatorExposes>

CarouselNext#

Props#

Defines valid properties in CarouselNext component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselNextInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselNextInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselNextPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselNextInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselNext component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselNext component.

name	type	default	description
root	CarouselNextPassThroughType<HTMLAttributes<HTMLButtonElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselNext component.

values
ComponentInstance<CarouselNextProps, CarouselNextState, CarouselNextExposes>

CarouselPrev#

Props#

Defines valid properties in CarouselPrev component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: CarouselPrevInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: CarouselPrevInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<CarouselPrevPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: CarouselPrevInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Exposes#

Defines the methods and properties exposed by CarouselPrev component.

name	type	default	description
carousel	CarouselRootInstance	null	The Carousel component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of CarouselPrev component.

name	type	default	description
root	CarouselPrevPassThroughType<HTMLAttributes<HTMLButtonElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of CarouselPrev component.

values
ComponentInstance<CarouselPrevProps, CarouselPrevState, CarouselPrevExposes>

useCarousel#

Props#

Defines valid properties in useCarousel.

name	type	default	description
autoSize	boolean	false	Whether the carousel should auto size.
orientation	"horizontal" \| "vertical"	'horizontal'	Orientation of the carousel.
align	"center" \| "start" \| "end"	'center'	Alignment of the carousel items.
loop	boolean	false	Whether the carousel should loop.
snapType	"mandatory" \| "proximity"	'mandatory'	Scroll snap type applied to the track.
spacing	number	16	Spacing between carousel items.
slidesPerPage	number	1	How many slides are visible per page. Supports fractions (e.g. 1.5).
page	number	undefined	Index of the active slide.
slide	number	undefined	Index of the active slide.
defaultPage	number	0	Default index of the active slide.
onPageChange	(event: useCarouselChangeEvent) => void	null	Callback fired when the carousel's page changes.
onSlideChange	(event: useCarouselChangeEvent) => void	null	Callback fired when the active slide (by value) changes.

State#

Defines valid state in useCarousel.

name	type	default	description
isPrevDisabled	boolean	null	Whether the "previous" navigation button should be disabled.
isNextDisabled	boolean	null	Whether the "next" navigation button should be disabled.
snapPoints	Set<number>	null	The snap points of the carousel.
page	number	null	The current page of the carousel.
swiping	boolean	null	Whether the user is currently swiping the carousel by touch.

Exposes#

Defines the methods and properties exposed by useCarousel.

name	type	default	description
state	useCarouselState	null	The state of the useCarousel.
contentRef	RefObject<HTMLDivElement>	null	Ref to the content element.
slidesPerPage	number	null	Number of slides displayed per page.
prev	() => void	null	Navigates to the previous slide.
next	() => void	null	Navigates to the next slide.
scrollTo	(value: number) => void	null	Scrolls to the specified value.
scrollToPage	(page: number) => void	null	Scrolls to the specified page.
scrollToSlide	(slide: number) => void	null	Scrolls to the specified slide value.
setToClosest	() => void	null	Scrolls to the closest snap point.
onContentPointerDown	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer down.
onContentPointerMove	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer move.
onContentPointerUp	(event: PointerEvent<HTMLDivElement>) => void	null	Event handler for content pointer up.
onContentWheel	(event: WheelEvent<HTMLDivElement>) => void	null	Event handler for content wheel.
resolveSnapType	() => string	null	Computes the appropriate CSS `scroll-snap-type` value based on orientation and snapping behavior.

Interfaces#

Types#

Instance

Instance of useCarousel headless.

values
HeadlessInstance<useCarouselProps, useCarouselState, useCarouselExposes>