Carousel

The Carousel component displays a series of slides that users can navigate using various controls.

To navigate through your slides, you can:

Use the provided controls.

Swipe or drag the slides.

Use your keyboard's left and right arrow keys.

Anatomy

The Carousel is made up of the following parts:

CarouselViewport – The viewport container for the carousel. It contains the scroll container and handles user interactions like swipe gestures or pointer events.

CarouselSlides – A container that arranges slides in a horizontal or vertical line.

CarouselSlide – An individual slide within the carousel.

CarouselPrevious – The control to navigate to the previous slide.

CarouselNext – The control to navigate to the next slide.

CarouselIndicator – A visual navigation element that shows the current slide. It can be styled as dots, thumbnails, tabs, or any custom element you prefer.

Adding a Carousel

Insert a Carousel from the Library.

You can add or remove slides within the Carousel as needed. To add new slides, you can either insert a new CarouselSlide from the Library, or duplicate an existing slide.

💡

Pro tip

To quickly duplicate slides, select a CarouselSlide and use the shortcut Cmd + D (Mac) or Ctrl + D (Windows).

Templates

Carousel: The default carousel, arranges slides horizontally

Vertical Carousel: Arranges slides vertically.

Carousel with Thumbnails: Provides small thumbnail previews for quick navigation.

Carousel with Progress: Displays a progress bar showing slide advancement.

Carousel with Controls: Offers play and pause buttons to control autoplay.

Carousel with Numbers: Displays the current slide number out of the total (e.g., "1 of 5").

Carousel with Tabs: Displays tabs for easy slide switching.

Carousel with Multiple Slides: Displays multiple slides simultaneously.

Guides

Creating Custom Slides

By default, a carousel slide consists of a single image, but it can be fully customized by adding, removing, and arranging elements within it. You can take advantage of this customization to create designs like testimonials, reviews, or service cards.

The video below demonstrates how to create a basic testimonial slide using the Column component, an Avatar, and Text elements for the user’s name and testimonial.

💡

Pro tip

Use classes to apply reusable styles across multiple slide items, ensuring a consistent appearance for each slide.

Setting the loop property

The loop property enables infinite looping, meaning the carousel seamlessly wraps around when reaching the last slide.

Select the Carousel component.

Navigate to the Properties Panel.

Click the plus icon (+) in the top right corner to add additional properties.

Select the loop property.

Set the value to true.

💡

Pro tip

Explore more properties in the Properties section.

Resizing the Carousel

You can control the size of your carousel by adjusting different layers depending on which part you want to change:

Carousel: This component affects the size of the carousel, including the control buttons. To adjust the size of the entire carousel:

Select the Carousel component.

In the Properties Panel, set the desired width.

CarouselViewport: This controls the visible area where the slides are displayed. To resize the viewport:

Select the CarouselViewport component.

Navigate to the Properties Panel and adjust the height as needed.

CarouselSlide: By default, the slides automatically adjust to fit the CarouselWrapper, so you typically don't need to resize them manually. However, if you want to display multiple slides at once, you will need to adjust the flex-basis of each slide.

💡

Pro tip

After resizing, preview the carousel on different breakpoints to ensure the layout looks consistent across various screen sizes.

Styling the Controls

Every part of the carousel, including navigation buttons and indicators, can be fully customized to match your design.

Examples include:

Previous and Next Buttons: Modify the appearance of CarouselPrevious and CarouselNext by adjusting their size, background, border, and icon styling. You can also replace the icon entirely.

Indicators: Customize CarouselIndicator by adjusting its size, spacing, and color. Use the States panel to define different styles for selected and unselected indicators.

All styling adjustments can be made in the Properties Panel.

💡

Pro tip

To apply the same styling to both controls, assign the same class to each button. Alternatively, you can duplicate the styled button and replace its icon with the appropriate one for CarouselNext or CarouselPrevious.

Displaying Multiple Slides

To display multiple slides simultaneously, you can start by using the preconfigured Carousel with Multiple Slides:

Open the Insert Menu, navigate to Components, and hover over Carousel.

Select “Carousel w/ Multiple Slides” from the list of available variants.

If you want to adjust the number of slides shown, select each CarouselSlide container and adjust its size accordingly. For example, if you want two slides to be visible simultaneously, set each slide’s flex-basis to 50%.

💡

Pro tip

Use the slidesToScroll property to control how many slides advance per navigation click or swipe. For instance, you can set slidesToScroll to 4 to move four slides on each scroll action.

💡

Pro tip

You can fine-tune how the slides are aligned within the carousel viewport using the align property, choosing from the start, center (default), or end.

Properties

Carousel

Property	Type	Default	Description
align	`‘start’ \| ‘center’ \| ‘end’`	`‘center’`	Align the slides relative to the carousel viewport.
autoPlay	`boolean`	`true`	If set to false, you’ll have to set autoplay manually by calling the autoplay method
axis	`‘x’ \| ‘y’`	`‘x’`	Choose scroll axis between `x` and `y`. Remember to stack your slides horizontally or vertically using CSS to match this option.
loop	`boolean`	`true`	Enables infinite looping.
slidesToScroll	`number`	`1`	Group slides together. Drag interactions, dot navigation, and previous/next buttons are mapped to group slides into the given number, which has to be an integer.
dragFree	`boolean`	`false`	Enables momentum scrolling. The duration of the continued scrolling is proportional to how vigorous the drag gesture is.
skipSnaps	`boolean`	`false`	Allow the carousel to skip scroll snaps if it's dragged vigorously. Note that this option will be ignored if the `dragFree` option is set to `true`.
duration	`number`	`25`	Set scroll duration when triggered by any of the API methods. Higher numbers enables slower scrolling. Drag interactions are not affected because duration is then determined by the drag force.
startIndex	`number`	`0`	Set the initial scroll snap to the given number. First snap index starts at `0`. Please note that this is not necessarily equal to the number of slides when used together with the `slidesToScroll` option.
active	`boolean`	`true`	Used to toggle the carousel active/inactive depending on media queries.
jump	`boolean`	`false`	When set to `true`, autoplay will do instant slide transitions when advancing.
delay	`number`	`4000`	Choose a delay between transitions in milliseconds. If you pass a number, the same delay will be applied to all transitions.
stopOnFocusin	`boolean`	`true`	When enabled, autoplay will stop when a focusable element inside the carousel recieves focus. If `stopOnInteraction` is `false`, autoplay will resume when the user leaves focus.
stopOninteraction	`boolean`	`true`	If set to `false`, autoplay will not be disabled after drag interactions, and it will restart every time after an interaction.
stopOnMouseEnter	`boolean`	`false`	When enabled, autoplay will stop when a mouse pointer enters the Carousel container. If `stopOnInteraction` is also `false`, autoplay will resume when the mouse leaves the carousel container.
stopOnLastSnap	`boolean`	`false`	If this parameter is enabled, autoplay will stop when it reaches last slide.

CarouselPrevious

Property	Type	Default	Description
jump	`boolean`	`false`	If `true`, the carousel wil jump to the previous slide instead of scrolling.

CarouselNext

Property	Type	Default	Description
jump	`boolean`	`false`	If `true`, the carousel wil jump to the next slide instead of scrolling.