Carousel
Browse through a series of content items
Source ↗️ Report Issue ↗️Use the Carousel
component to display images, text, or cards, that can be navigated by sliding or clicking through them one at a time. They are particularly useful for showcasing multiple pieces of content in a compact space. Use them for image galleries, featured content, testimonial slides, promotions or ads, onboarding steps, or for portfolio display.
- 1
- 2
- 3
To use the Carousel
component, specify the number of slides using the items
prop, and create the slides as children of the component. Each child must be wrapped inside an li
element. Here you can pass any element to create image, card, or other types of carousels. To properly display each slide, make sure you set their width
to 100%
in your CSS.
Custom Pagination
The Carousel
component uses the Pagination
component to render the pagination under the slides. Using the pagination
prop, you can customize the pagination in any way you can customize the Pagination
component. For a full list of possible props, see the API of the Pagination
component.
- 1
- 2
- 3
- 1
- 2
- 3
- 1
- 2
Pagination with Label
Pagination can also be created with labels. Use the subText
prop to display a text under the slides:
- 1
- 2
- 3
You can use the special {0}
and {1}
placeholders to insert the current slide, and the total number of slides into your label.
Progress Bar
If you’d like to use a carousel as a list of steps, you might want to display a progress bar for the user to visually indicate their progress. This can be achieved by setting the progress
prop to true
:
- 1
- 2
- 3
Multiple Items per Slide
To display multiple items per slide, you can use the itemsPerSlide
prop. When itemsPerSlide
is set, scroll snapping is automatically disabled.
- 1
- 2
- 3
- 4
- 5
- 6
- 1
- 2
- 3
- 4
- 5
- 6
Transition Effects
The Carousel
component also comes with two transition effect out of the box:
opacity
: Fades in the next slide.saturate
: Animates inactive slides from black and white to colored.
The effect can be configured using the effect
prop:
The correct style is applied based on the state of the slide (active/inactive). To mark the first slide as the active element, you must set the data-active
attribute to true
on the li
element. If no data-active
attribute is present during the initial render, all slides will have the effect of the inactive state.
Image and Component Carousels
You can combine the Carousel
component with images or other component to create image carousels, onboarding steps, promotional sliders or other types of carousels.
- Astro
- Svelte
- React
- NoteYou can put any component inside a carousel to create various elements.
- InfoMake sure to set the element’s width to
100%
to properly display each slide across all devices. - Combine multiple components to create interactive slides.
Carousel Performance
The Carousel
component listens to scroll events to update its state when slides are swiped on touch devices. By default, this event is debounced to reduce the number of function calls and improve its JavaScript performance.
As a result, this may cause a slight delay in state update when the carousel is navigated using a swipe motion. This functionality can be configured or turned off using the debounce
prop:
debounce
prop will effect mobile navigation performance. Another way to customize mobile navigation, is using the scrollSnap
prop. When slides are scrolled using a swipe motion, the carousel will snap to the next slide. This scroll snap behavior can also be turned off using the scrollSnap
prop:
API
Prop | Purpose |
---|---|
items | Set the number of slides. |
itemsPerSlide | Sets the number of items per slide. |
subText | Sets a label under the slides. |
scrollSnap | Sets scroll snap for swipe motion. Enabled by default. |
progress | Displays a progress bar under the slides. Defaults to false . |
pagination | Customize the pagination of the carousel. It can accept the props of the Pagination component. |
effect | Sets a transition effect for the slides. Can be one of opacity , saturate . |
debounce | Sets the debounce amount for the scroll event listener. |
className | Pass additional CSS classes for the carousel. |
wrapperClassName | Pass additional CSS classes for slides container. |
paginationClassName | Pass additional CSS classes for the pagination of the carousel. |
Svelte & React Prop | Purpose |
---|---|
onScroll | Attach event listeners that are triggered when the carousel is scrolled. The page parameter will return the current page as a number. |
Request improvement for this page