Carousel

Display and cycle through a collection of items.

Dependencies

• Swipe Content

How to

The Carousel component can be used to cycle through a series of items (cards, images, etc.), with the option of displaying multiple items at the same time.

---

🔍 On this page:

1. Options
2. Carousel Item Number
3. Carousel as Slideshow
4. Carousel Dots Navigation
5. Carousel Counter
6. Carousel Items with custom JavaScript
7. Center Items
8. Active Items Event

Options #

You can edit the following data attributes to customize the carousel behavior:

• drag: to enable drag on touch devices, add a data-drag="on" to the js-carousel element (default is off);
• autoplay: to enable autoplay, add a data-autoplay="on" to the js-carousel element (default is off). Autoplay is automatically paused when user hovers over the carousel element, interacts with the carousel contents or the carousel controls;
• autoplay interval: to set a custom autoplay timing, add a data-autoplay-interval equal to the custom duration (in milliseconds) that you want to use (default is 5000). This option is effective only if data-autoplay is on;
• autoplay on hover: if you do not want to pause autoplay when hovering over the carousel, add a data-autoplay-hover="on" to the js-carousel element (default is off). This option is effective only if data-autoplay is on; 
• autoplay on focus: if you do not want to pause autoplay when a carousel element is in focus, add a data-autoplay-focus="on" to the js-carousel element (default is off). This option is effective only if data-autoplay is on; 
• infinite loop: to disable infinite loop, add a data-loop="off" to the js-carousel element (default is on);
• carousel navigation: to create the carousel dots navigation, add a data-navigation="on" (default is off); this option is available when data-loop="off".

Carousel Item Number #

The number of items visible in a carousel cycle is determined based on:

• item mininum width: this is equal to the width of the .carousel__item as defined in the carousel.scss file. To modify this value, you can change the --carousel-item-auto-size CSS variable (default is 260px);
• item right margin: this will set the gap between two consecutive items. To modify this value, you can change the --carousel-grid-gap CSS variable defined inside the carousel.scss file (default is var(--space-xs)).

Carousel as Slideshow #

If you want to use the Carousel component to create a slideshow (one single item visible at a time), you can:

• set the --carousel-item-auto-size CSS variable equal to 100%;
• set the --carousel-grid-gap CSS variable equal to zero;

For example, define your custom carousel class:

.carousel--slideshow {
  --carousel-item-auto-size: 100%;
  --carousel-grid-gap: 0;
}

and apply it to your carousel element:

<div class="carousel carousel--slideshow js-carousel">
  <!-- carousel content here -->
</div>

Carousel Dots Navigation #

To add a navigation to the carousel, add a data-navigation="on" attribute to the .js-carousel element (applicable if data-loop="off"):

<div class="carousel js-carousel" data-loop="off" data-navigation="on">
  <!-- carousel content here -->
</div>

You can customize the carousel navigation using the following data attributes:

• data-navigation-class: pass a list of custom classes to be added to the navigation element (default is carousel__navigation);
• data-navigation-item-class: pass a custom class for the navigation list items (default is carousel__nav-item). When an item is selected, the class {navigation-item-class}--selected is added to that element (e.g., if data-navigation-item-class='carousel__navigation-item', the selected class will be carousel__navigation-item--selected);
• data-navigation-pagination: set it to 'on' to use the carousel navigation as a pagination element (see --pagination variation demo).

Carousel Counter #

You can add a counter to your carousel (see --counter variation demo): add the .js-carousel__counter and the .js-carousel__counter-tot classes to the counter and the total elements respectively:

<div class="carousel js-carousel">
  <!-- carousel content here -->

  <span class="js-carousel__counter"></span>/<span class="js-carousel__counter-tot"></span>
</div>

Carousel Items with custom JavaScript #

If data-loop="on" (default option), the Carousel plugin removes carousel items and reinsert clones of those items when required. For this reason, custom JS code applied to the carousel items (e.g., event listeners) may not work after a loop has been completed.

In this case, we suggest to set the data-loop option to off.

In the cases where you still need to have the infinite loop, you can solve this problem re-initializing your custom code when new clones are created. Use the carousel-updated event to target new clone items:

var carousel = document.getElementsByClassName('js-carousel')[0];
carousel.addEventListener('carousel-updated', function(event){
  // reinitialize your custom js here
  // event.detail -> list of clone items 
});

For example, if your carousel item includes a slideshow, you would need:

var carousel = document.getElementsByClassName('js-carousel')[0];
carousel.addEventListener('carousel-updated', function(event){
  // event.detail -> list of clone items
  for(var i = 0; i < event.detail.length; i++) {
    var slideshow = event.detail[i].getElementsByClassName('js-slideshow');
    if(slideshow.length > 0) {
      new Slideshow({element: slideshow[0]});
    }
  }
});

Center Items #

If the carousel items number is smaller than the number of visible items, and you want them to be centered in the viewport, add a data-justify-content="on" to the .carousel item. By default items will be aligned to the left:

<div class="carousel flex flex-column js-carousel" data-loop="off" data-justify-content="on">
  <!-- carousel content -->
</div>

Active Items Event #

Each time a new group of carousel items are reveled, the carousel-active-items custom event is emitted. This event can be used to detect the first visible item in the carousel, and the total number of visible items:

var carousel = document.getElementsByClassName('js-carousel')[0];

carousel.addEventListener('carousel-active-items', function(event){
  // event.detail.firstSelectedItem -> first visible item
  // event.detail.visibleItemsNb -> number of visible items
});

Dynamic Content #

If your carousel content is created dynamically, you may need to initialize it (once it has been added to the page) to make it work properly.

Once the dynamic content has been added to the page, initialize it using the Carousel object:

var carouselEl = document.getElementsByClassName('carousel')[0];

new Carousel({
  element: carouselEl,
  autoplay : false, // enable/disable autoplay
  autoplayInterval: false, // in milliseconds - default is 5000 (5s)
  loop: false, // enable/disable infinite loop
  nav: true, // add carousel dots navigation
  drag: false // enable/disable drag
});

Categories

• Plugins > Carousel

Bug report & feedback

Component Github page ↗