---
meta:
title: Carousel
description: Carousels display an arbitrary number of content slides along a horizontal or vertical axis.
layout: component
---
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
<>
>
);
```
## Examples
### Pagination
Use the `pagination` attribute to show the total number of slides and the current slide as a set of interactive dots.
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
);
```
### Navigation
Use the `navigation` attribute to show previous and next buttons.
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
);
```
### Looping
By default, the carousel will not advanced beyond the first and last slides. You can change this behavior and force the carousel to "wrap" with the `loop` attribute.
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
);
```
### Autoplay
The carousel will automatically advance when the `autoplay` attribute is used. To change how long a slide is shown before advancing, set `autoplay-interval` to the desired number of milliseconds. For best results, use the `loop` attribute when autoplay is enabled. Note that autoplay will pause while the user interacts with the carousel.
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
);
```
### Mouse Dragging
The carousel uses [scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Scroll_Snap) to position slides at various snap positions. This allows users to scroll through the slides very naturally, especially on touch devices. Unfortunately, desktop users won't be able to click and drag with a mouse, which can feel unnatural. Adding the `mouse-dragging` attribute can help with this.
This example is best demonstrated using a mouse. Try clicking and dragging the slide to move it. Then toggle the switch and try again.
```html:preview
```
```jsx:react
import { useState } from 'react';
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
const App = () => {
const [isEnabled, setIsEnabled] = useState(false);
return (
<>
setIsEnabled(!isEnabled)}>
Enable mouse dragging
>
);
};
```
### Multiple Slides Per View
The `slides-per-page` attribute makes it possible to display multiple slides at a time. You can also use the `slides-per-move` attribute to advance more than once slide at a time, if desired.
```html:preview
Slide 1
Slide 2
Slide 3
Slide 4
Slide 5
Slide 6
```
{% raw %}
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const App = () => (
Slide 1
Slide 2
Slide 3
Slide 4
Slide 5
Slide 6
);
```
{% endraw %}
### Adding and Removing Slides
The content of the carousel can be changed by adding or removing carousel items. The carousel will update itself automatically.
```html:preview
Slide 1
Slide 2
Slide 3
Add slide
Remove slide
```
{% raw %}
```jsx:react
import { useState } from 'react';
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const css = `
.dynamic-carousel {
--aspect-ratio: 3 / 2;
}
.dynamic-carousel ~ .carousel-options {
display: flex;
justify-content: center;
margin-top: var(--sl-spacing-large);
}
.dynamic-carousel sl-carousel-item {
flex: 0 0 100%;
display: flex;
align-items: center;
justify-content: center;
color: white;
font-size: var(--sl-font-size-2x-large);
}
`;
const App = () => {
const [slides, setSlides] = useState(['#204ed8', '#be133d', '#6e28d9']);
const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'violet'];
const addSlide = () => {
setSlides([...slides, getRandomColor()]);
};
const removeSlide = () => {
setSlides(slides.slice(0, -1));
};
return (
<>
{slides.map((color, i) => (
Slide {i}
))}
Add slide
Remove slide
>
);
};
```
{% endraw %}
### Vertical Scrolling
Setting the `orientation` attribute to `vertical` will render the carousel in a vertical layout. If the content of your slides vary in height, you will need to set amn explicit `height` or `max-height` on the carousel using CSS.
```html:preview
```
```jsx:react
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
const css = `
.vertical {
max-height: 400px;
}
.vertical::part(base) {
grid-template-areas: 'slides slides pagination';
}
.vertical::part(pagination) {
flex-direction: column;
}
.vertical::part(navigation) {
transform: rotate(90deg);
display: flex;
}
`;
const App = () => (
<>
>
);
```
### Aspect Ratio
Use the `--aspect-ratio` custom property to customize the size of the carousel's viewport from the default value of 16/9.
```html:preview
1/1
3/2
16/9
```
{% raw %}
```jsx:react
import { useState } from 'react';
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
import SlSelect from '@shoelace-style/shoelace/dist/react/select';
import SlOption from '@shoelace-style/shoelace/dist/react/option';
const App = () => {
const [aspectRatio, setAspectRatio] = useState('3/2');
return (
<>
setAspectRatio(event.target.value)}
>
1 / 1
3 / 2
16 / 9
>
);
};
```
{% endraw %}
### Scroll Hint
Use the `--scroll-hint` custom property to add inline padding in horizontal carousels and block padding in vertical carousels. This will make the closest slides slightly visible, hinting that there are more items in the carousel.
```html:preview
```
{% raw %}
```jsx:react
import { useState } from 'react';
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
import SlRange from '@shoelace-style/shoelace/dist/react/range';
const App = () => (
<>
>
);
```
{% endraw %}
### Gallery Example
The carousel has a robust API that makes it possible to extend and customize. This example syncs the active slide with a set of thumbnails, effectively creating a gallery-style carousel.
```html:preview
```
```jsx:react
import { useRef } from 'react';
import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
import SlRange from '@shoelace-style/shoelace/dist/react/range';
const css = `
.carousel-thumbnails {
--slide-aspect-ratio: 3 / 2;
}
.thumbnails {
display: flex;
justify-content: center;
}
.thumbnails__scroller {
display: flex;
gap: var(--sl-spacing-small);
overflow-x: auto;
scrollbar-width: none;
scroll-behavior: smooth;
scroll-padding: var(--sl-spacing-small);
}
.thumbnails__scroller::-webkit-scrollbar {
display: none;
}
.thumbnails__image {
width: 64px;
height: 64px;
object-fit: cover;
opacity: 0.3;
will-change: opacity;
transition: 250ms opacity;
cursor: pointer;
}
.thumbnails__image.active {
opacity: 1;
}
`;
const images = [
{
src: '/assets/examples/carousel/mountains.jpg',
alt: 'The sun shines on the mountains and trees (by Adam Kool on Unsplash'
},
{
src: '/assets/examples/carousel/waterfall.jpg',
alt: 'A waterfall in the middle of a forest (by Thomas Kelly on Unsplash'
},
{
src: '/assets/examples/carousel/sunset.jpg',
alt: 'The sun is setting over a lavender field (by Leonard Cotte on Unsplash'
},
{
src: '/assets/examples/carousel/field.jpg',
alt: 'A field of grass with the sun setting in the background (by Sapan Patel on Unsplash'
},
{
src: '/assets/examples/carousel/valley.jpg',
alt: 'A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash'
}
];
const App = () => {
const carouselRef = useRef();
const thumbnailsRef = useRef();
const [currentSlide, setCurrentSlide] = useState(0);
useEffect(() => {
const thumbnails = Array.from(thumbnailsRef.current.querySelectorAll('.thumbnails__image'));
thumbnails[currentSlide]..scrollIntoView({
block: 'nearest'
});
}, [currentSlide]);
const handleThumbnailClick = (index) => {
carouselRef.current.goToSlide(index);
}
const handleSlideChange = (event) => {
const slideIndex = e.detail.index;
setCurrentSlide(slideIndex);
}
return (
<>
{images.map({ src, alt }) => (
)}
>
);
};
```