Installation
Usage
import { Carousel, CarouselControl, CarouselItem, CarouselContent, CarouselIndicator, CarouselIndicatorGroup, CarouselNext, CarouselPrevious, } from "@/components/ui/carousel";
<Carousel> <CarouselControl> <CarouselPrevious>Previous</CarouselPrevious> <CarouselNext>Next</CarouselNext> </CarouselControl> <CarouselContent> <CarouselItem /> <CarouselItem /> <CarouselItem /> </CarouselContent> </Carousel>
Orientation
You can change the orientation of the carousel using the orientation prop.
Horizontal
Vertical
Thumbnail Indicators
Render each thumbnail inside <CarouselIndicator /> to create a visual preview of each slide.
Use the orientation prop to change the orientation of the thumbnail indicators.
Horizontal
Vertical
Examples
Autoplay
Use autoplay props on <Carousel /> to make the carousel play automatically.
Loop
Use the loop prop to make the carousel loop.
Controlled
Use the page and onPageChange props to control the carousel state programmatically.
Current page: 1 of 5
Slides Per Page
Display multiple slides simultaneously by setting the slidesPerPage prop on <Carousel />.
Spacing
Control the gap between slides using the spacing prop on <Carousel />.
Spacing is in multiples of 4px. Example: spacing={10} will set the spacing to 40px.
Padding
Control the padding around the carousel using the padding prop on <Carousel />.
Padding is in multiples of 4px. Example: padding={10} will set the padding to 40px.
Mouse Drag
To allow mouse drag, set the allowMouseDrag prop on <Carousel />.
API Reference
Carousel
Root element of the carousel. Renders a div
| Prop | Type | Default |
|---|---|---|
slideCount | number | required |
allowMouseDrag | boolean | false |
autoplay | boolean | { delay: number } | false |
defaultPage | number | 0 |
loop | boolean | false |
orientation | 'horizontal' | 'vertical' | 'horizontal' |
page | number | - |
slidesPerPage | number | 1 |
slidesPerMove | number | 'auto' | 'auto' |
snapType | 'proximity' | 'mandatory' | 'mandatory' |
spacing | number | '4' |
padding | number | 0 |
inViewThreshold | number | number[] | 0.6 |
className | string | - |
onPageChange | ({ page }: PageChangeDetails) => void | - |
onAutoplayStatusChange | ({ isPlaying, page, type }: AutoplayStatusDetails) => void | - |
onDragStatusChange | ({ isDragging, page, type }: DragStatusDetails) => void | - |
CarouselContent
Container for carousel items. Renders a div
| Prop | Type | Default |
|---|---|---|
className | string | - |
CarouselItem
Container for a single carousel item. Renders a div
| Prop | Type | Default |
|---|---|---|
index | number | required |
snapAlign | 'start' | 'center' | 'end' | 'start' |
className | string | - |
CarouselControl
Container for carousel navigation controls. Renders a div
| Prop | Type | Default |
|---|---|---|
className | string | - |
CarouselPrevious
Button that navigates to the previous slide. Renders a button
| Prop | Type | Default |
|---|---|---|
className | string | - |
CarouselNext
Button that navigates to the next slide. Renders a button
| Prop | Type | Default |
|---|---|---|
className | string | - |
CarouselIndicatorGroup
Container for carousel indicators. Renders a div
| Prop | Type | Default |
|---|---|---|
className | string | - |
CarouselIndicator
Button that indicates and navigates to a specific slide. Renders a button
| Prop | Type | Default |
|---|---|---|
index | number | required |
readOnly | boolean | false |
className | string | - |
For a complete list of props, see the Ark UI documentation.