Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

Carousel

Used to cycle through a series of visual content within a container.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server

Usage

import { Carousel } from "@chakra-ui/react"
<Carousel.Root>
  <Carousel.ItemGroup>
    <Carousel.Item />
  </Carousel.ItemGroup>
  <Carousel.Control>
    <Carousel.AutoplayTrigger>
      <Carousel.AutoplayIndicator />
    </Carousel.AutoplayTrigger>
    <Carousel.PrevTrigger />
    <Carousel.Indicators />
    <Carousel.NextTrigger />
    <Carousel.ProgressText />
  </Carousel.Control>
</Carousel.Root>

Shortcuts

The Carousel component also provides convenient shortcuts for common patterns.

Carousel.Indicators

The Carousel.Indicators shortcut renders a full set of indicators automatically based on the number of slides.

<Carousel.IndicatorGroup>
  {Array.from({ length: items.length }, (_, index) => (
    <Carousel.Indicator key={index} index={index} />
  ))}
</Carousel.IndicatorGroup>

This might be more concise if you don't need to customize each indicator:

<Carousel.Indicators />

Examples

Controlled

Use the page and onPageChange props to programatically control the active carousel page.

Store

Alternatively, use the useCarousel hook to create a carousel store and pass it to the Carousel.RootProvider component for full programmatic control.

Arrows

Use the Carousel.PrevTrigger and Carousel.NextTrigger components to create arrows that navigate between slides.

Indicators

Use the Carousel.Indicators component to render visual indicators that help users track the progress of the carousel and jump to specific slides.

Thumbnail Indicators

Here's an example that uses an image thumbnail as a custom indicator.

Spacing

Use the spacing prop to control the spacing between slides.

spacing='48px'

Vertical

Use the orientation prop to vertical to transform your carousel into a vertical slider.

Mouse Drag

Use the allowMouseDrag prop to enable mouse dragging on the carousel.

Click and drag to change slides

Autoplay

Pass the autoplay prop to the Carousel.Root component to make the carousel automatically move between slides.

autoplay={{ delay: 2000 }} or autoplay={true}

Compose the Carousel component with the Dialog component to create a lightbox.

Here's an example that shows how to create an image carousel for a product showcase.

Property Card

Here's an example that shows how to compose the Carousel component with other components to create a property card carousel.

Popular homes in Cape Town

Props

Root

PropDefaultType
slideCount *
number

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

allowMouseDrag false
boolean

Whether to allow scrolling via dragging with mouse

autoplay false
boolean | { delay: number }

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

defaultPage 0
number

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

inViewThreshold 0.6
number | number[]

The threshold for determining if an item is in view.

loop false
boolean

Whether the carousel should loop around.

orientation 'horizontal'
'horizontal' | 'vertical'

The orientation of the element.

slidesPerMove 'auto'
number | 'auto'

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.

slidesPerPage 1
number

The number of slides to show at a time.

snapType 'mandatory'
'proximity' | 'mandatory'

The snap type of the item.

spacing 0px
string

The amount of space between items.

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

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

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

onAutoplayStatusChange
(details: AutoplayStatusDetails) => void

Function called when the autoplay status changes.

onDragStatusChange
(details: DragStatusDetails) => void

Function called when the drag status changes.

onPageChange
(details: PageChangeDetails) => void

Function called when the page changes.

padding
string

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

page
number

The controlled page of the carousel.

translations
IntlTranslations

The localized messages to use.

ItemGroup

PropDefaultType
as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Item

PropDefaultType
index *
number

The index of the item.

snapAlign 'start'
'center' | 'end' | 'start'

The snap alignment of the item.

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Control

PropDefaultType
as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Explorer

Explore the Carousel component parts interactively. Click on parts in the sidebar to highlight them in the preview.

1 / 5

Component Anatomy

Hover to highlight, click to select parts

root

itemGroup

item

control

nextTrigger

prevTrigger

indicatorGroup

indicator

autoplayTrigger

carousel.recipe.ts

Previous

Breadcrumb

Next

Collapsible