1. framework components
  2. ›
  3. carousel

Carousel

Navigate through a collection of slides with controls and indicators.

Warning

This feature is currently marked as beta and not intended for production use. It may receive breaking changes before its stable release.

Breaking convention in Skeleton, some portions of this component are provided “headless”. Meaning no default styles are applied out of the box. This ensures you retain full control of styling for maximum flexibility.

Overlapping Controls

Introduce supporting elements and styles to implement this variation.

Orientation

Apply orientation="vertical" on the root, and apply a set height on the <Carousel.ItemGroup>.

Text

Display a text display of the carousel state.

Showing 1 of 3

Anatomy

Here’s an overview of how the Carousel component is structured in code:

tsx 
import { Carousel } from '@skeletonlabs/skeleton-react';

export default function Anatomy() {
	return (
		<Carousel>
			<Carousel.Control>
				<Carousel.PrevTrigger />
				<Carousel.AutoplayTrigger />
				<Carousel.NextTrigger />
			</Carousel.Control>
			<Carousel.ItemGroup>
				<Carousel.Item />
			</Carousel.ItemGroup>
			<Carousel.IndicatorGroup>
				<Carousel.Indicator />
			</Carousel.IndicatorGroup>
			<Carousel.ProgressText />
		</Carousel>
	);
}

API Reference

Root

PropDefaultType
ids—Partial<{ root: string; item: (index: number) => string; itemGroup: string; nextTrigger: string; prevTrigger: string; indicatorGroup: string; indicator: (index: number) => string; }> | undefined

The ids of the elements in the carousel. Useful for composition.

translations—IntlTranslations | undefined

The localized messages to use.

slidesPerPage1number | undefined

The number of slides to show at a time.

autoSizefalseboolean | undefined

Whether to enable variable width slides.

slidesPerMove"auto"number | "auto" | undefined

The number of slides to scroll at a time. When set to `auto`, the number of slides to scroll is determined by the `slidesPerPage` property.

autoplayfalseboolean | { delay: number; } | undefined

Whether to scroll automatically. The default delay is 4000ms.

allowMouseDragfalseboolean | undefined

Whether to allow scrolling via dragging with mouse

loopfalseboolean | undefined

Whether the carousel should loop around.

page—number | undefined

The controlled page of the carousel.

defaultPage0number | undefined

The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel.

spacing"0px"string | undefined

The amount of space between items.

padding—string | undefined

Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view.

onPageChange—((details: PageChangeDetails) => void) | undefined

Function called when the page changes.

inViewThreshold0.6number | number[] | undefined

The threshold for determining if an item is in view.

snapType"mandatory""proximity" | "mandatory" | undefined

The snap type of the item.

slideCount—number

The total number of slides. Useful for SSR to render the initial ating the snap points.

onDragStatusChange—((details: DragStatusDetails) => void) | undefined

Function called when the drag status changes.

onAutoplayStatusChange—((details: AutoplayStatusDetails) => void) | undefined

Function called when the autoplay status changes.

dir"ltr""ltr" | "rtl" | undefined

The document's text/writing direction.

getRootNode—(() => ShadowRoot | Node | Document) | undefined

A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

orientation"horizontal""horizontal" | "vertical" | undefined

The orientation of the element.

element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Provider

PropDefaultType
value—CarouselApi<PropTypes>

element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Context

PropDefaultType
children—(carousel: CarouselApi<PropTypes>) => ReactNode

Control

PropDefaultType
element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

ItemGroup

PropDefaultType
element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Item

PropDefaultType
index—number

The index of the item.

snapAlign"start""start" | "end" | "center" | undefined

The snap alignment of the item.

element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

PrevTrigger

PropDefaultType
element—((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

NextTrigger

PropDefaultType
element—((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

AutoplayTrigger

PropDefaultType
element—((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

IndicatorGroup

PropDefaultType
element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Indicator

PropDefaultType
index—number

The index of the indicator.

readOnlyfalseboolean | undefined

Whether the indicator is read only.

element—((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

ProgressText

PropDefaultType
element—((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

View page on GitHub