---
title: Carousel
description: A carousel with motion and swipe built using Embla.
base: base
component: true
links:
doc: https://www.embla-carousel.com/get-started/react
api: https://www.embla-carousel.com/api
---
## About
The carousel component is built using the [Embla Carousel](https://www.embla-carousel.com/) library.
## Installation
Command
Manual
```bash
npx shadcn@latest add carousel
```
Install the following dependencies:
```bash
npm install embla-carousel-react
```
Copy and paste the following code into your project.
Update the import paths to match your project setup.
## Usage
```tsx showLineNumbers
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselNext,
CarouselPrevious,
} from "@/components/ui/carousel"
```
```tsx showLineNumbers
...
...
...
```
## Examples
### Sizes
To set the size of the items, you can use the `basis` utility class on the ``.
```tsx showLineNumbers {4-6}
// 33% of the carousel width.
...
...
...
```
```tsx showLineNumbers {4-6}
// 50% on small screens and 33% on larger screens.
...
...
...
```
### Spacing
To set the spacing between the items, we use a `pl-[VALUE]` utility on the `` and a negative `-ml-[VALUE]` on the ``.
```tsx showLineNumbers /-ml-4/ /pl-4/
...
...
...
```
```tsx showLineNumbers /-ml-2/ /pl-2/ /md:-ml-4/ /md:pl-4/
...
...
...
```
### Orientation
Use the `orientation` prop to set the orientation of the carousel.
```tsx showLineNumbers /vertical | horizontal/
...
...
...
```
## Options
You can pass options to the carousel using the `opts` prop. See the [Embla Carousel docs](https://www.embla-carousel.com/api/options/) for more information.
```tsx showLineNumbers {2-5}
...
...
...
```
## API
Use a state and the `setApi` props to get an instance of the carousel API.
```tsx showLineNumbers {1,4,22}
import { type CarouselApi } from "@/components/ui/carousel"
export function Example() {
const [api, setApi] = React.useState()
const [current, setCurrent] = React.useState(0)
const [count, setCount] = React.useState(0)
React.useEffect(() => {
if (!api) {
return
}
setCount(api.scrollSnapList().length)
setCurrent(api.selectedScrollSnap() + 1)
api.on("select", () => {
setCurrent(api.selectedScrollSnap() + 1)
})
}, [api])
return (
...
...
...
)
}
```
## Events
You can listen to events using the api instance from `setApi`.
```tsx showLineNumbers {1,4-14,16}
import { type CarouselApi } from "@/components/ui/carousel"
export function Example() {
const [api, setApi] = React.useState()
React.useEffect(() => {
if (!api) {
return
}
api.on("select", () => {
// Do something on select.
})
}, [api])
return (
...
...
...
)
}
```
See the [Embla Carousel docs](https://www.embla-carousel.com/api/events/) for more information on using events.
## Plugins
You can use the `plugins` prop to add plugins to the carousel.
```ts showLineNumbers {1,6-10}
import Autoplay from "embla-carousel-autoplay"
export function Example() {
return (
// ...
)
}
```
## RTL
To enable RTL support in shadcn/ui, see the [RTL configuration guide](/docs/rtl).
When localizing the carousel for RTL languages, you need to set the `direction` option in the `opts` prop to match the text direction. This ensures the carousel scrolls in the correct direction.
```tsx showLineNumbers {2-5}
...
...
...
```
The `direction` option accepts `"ltr"` or `"rtl"` and should match the `dir` prop value. You may also want to rotate the navigation buttons using the `rtl:rotate-180` class to ensure they point in the correct direction.
## API Reference
See the [Embla Carousel docs](https://www.embla-carousel.com/api/plugins/) for more information on props and plugins.