Carousel

An unstyled, accessible carousel component with compound composition.

Build fully custom content sliders with complete control over layout, navigation, and indicators.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Carousel with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Content, Item, Prev, Next, Indicators, Indicator
CSS scroll-snap based navigation with configurable alignment and snap type
Mouse swipe gestures with automatic snap-to-closest behavior
IntersectionObserver-driven data-inview attribute on items
Horizontal and vertical orientation
Fractional slidesPerPage for partial item visibility

Usage#

import { Carousel } from 'primereact/carousel';

<Carousel.Root>
    <Carousel.Content>
        <Carousel.Item></Carousel.Item>
    </Carousel.Content>
    <Carousel.Indicators />
    <Carousel.Prev></Carousel.Prev>
    <Carousel.Next></Carousel.Next>
</Carousel.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Carousel.Root as="section">
    <Carousel.Content as="ul">
        <Carousel.Item as="li"></Carousel.Item>
    </Carousel.Content>
</Carousel.Root>

Default elements: Root=div, Content=div, Item=div, Prev=button, Next=button, Indicators=div, Indicator=button.

Render Function Children#

Indicators accepts a render function as children, providing access to the component instance. The instance exposes carousel (root instance with state.snapPoints).

<Carousel.Indicators>{(instance) => Array.from(instance.carousel?.state.snapPoints ?? []).map((_, i) => <Carousel.Indicator key={i} page={i}></Carousel.Indicator>)}</Carousel.Indicators>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

CarouselRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselRootInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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`	—
Callback fired when the carousel's page changes.
`onSlideChange`	`(event: useCarouselChangeEvent) => void`	—
Callback fired when the active slide (by value) changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-orientation`	`"horizontal"` or `"vertical"`
`data-align`	`"start"`, `"center"`, or `"end"`
`data-page`	Current page index
`data-swiping`	Present when user is swiping
`data-autosize`	Present when `autoSize` is enabled

Defines passthrough(pt) options of Carousel component.

label	type	description
root	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
content	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the content's DOM element.
item	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the item's DOM element.
prev	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the prev button's DOM element.
next	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the next button's DOM element.
indicators	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the indicators' DOM element.
indicator	CarouselRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the indicator's DOM element.

CarouselContent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselContentInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselContentInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselContentInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselContentPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselContentInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-orientation`	`"horizontal"` or `"vertical"`
`data-align`	`"start"`, `"center"`, or `"end"`
`data-page`	Current page index
`data-swiping`	Present when user is swiping
`data-autosize`	Present when `autoSize` is enabled

CSS Custom Properties

The Content element sets three CSS custom properties on its style for use in item sizing and layout.

CSS Variable	Description
`--slides-per-page`	Number of visible slides per page, derived from `slidesPerPage`.
`--spacing-items`	Gap between items in pixels, derived from `spacing`.
`--scroll-snap-type`	Resolved scroll-snap-type value (e.g. `x mandatory`).

Defines passthrough(pt) options of CarouselContent component.

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

CarouselItem#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselItemInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselItemInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselItemInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselItemPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselItemInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-value`	Item value identifier
`data-inview`	Present when item is in viewport
`data-orientation`	`"horizontal"` or `"vertical"`
`data-align`	`"start"`, `"center"`, or `"end"`
`data-autosize`	Present when `autoSize` is enabled

Defines passthrough(pt) options of CarouselItem component.

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

CarouselPrev#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselPrevInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselPrevInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselPrevInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselPrevPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselPrevInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-disabled`	Present when navigation is disabled
`data-orientation`	`"horizontal"` or `"vertical"`

Defines passthrough(pt) options of CarouselPrev component.

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

CarouselNext#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselNextInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselNextInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselNextInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselNextPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselNextInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-disabled`	Present when navigation is disabled
`data-orientation`	`"horizontal"` or `"vertical"`

Defines passthrough(pt) options of CarouselNext component.

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

CarouselIndicators#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselIndicatorsInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselIndicatorsInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselIndicatorsInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselIndicatorsPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselIndicatorsInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-orientation`	`"horizontal"` or `"vertical"`

Defines passthrough(pt) options of CarouselIndicators component.

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

CarouselIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CarouselIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CarouselIndicatorInstance) => string)`	—
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>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CarouselIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CarouselIndicatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CarouselIndicatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`page`	`number`	—
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-active`	Present when indicator is active
`data-orientation`	`"horizontal"` or `"vertical"`

Defines passthrough(pt) options of CarouselIndicator component.

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

Accessibility#

Carousel uses semantic HTML with button elements for navigation controls and indicators. Navigation buttons should include descriptive labels via aria-label. The current page can be announced with an aria-live region.

<Carousel.Root>
    <Carousel.Content aria-label="Image carousel">
        <Carousel.Item></Carousel.Item>
    </Carousel.Content>
    <Carousel.Prev aria-label="Previous slide"></Carousel.Prev>
    <Carousel.Next aria-label="Next slide"></Carousel.Next>
</Carousel.Root>

Keyboard Support#

Key	Function
`tab`	Moves focus between navigation buttons and indicators.
`enter` / `space`	Activates the focused button or indicator.