Documentation

Class: Carousel

ML. Carousel

  • A component for cycling through images, text and other elements, like a carousel.
  • Nested carousels are not supported, and generally not compliant with accessibility standards.
  • Each carousel should have a unique id attribute.
  • Every initialized carousel gets MLCarousel added to the element.
  • When setting arrowKeys: true, please note you need to focus on the carousel or an element within the carousel for the arrow keys to work correctly.
  • js-carousel-initialized class name gets added to the carousel element.
  • You can initialize carousels via data-carousel or JavaScript.
  • Carousel should be formatted as an unordered list <ul> and each <li> should have a class name of carousel-slide, i.e. <li class="carousel-slide"></li>
  • You can listen to custom events fired by the carousel. The carousel and carousel options are returned. See example below.
  • See it in action + some notes! 😀
Event Name Description
carousel.init Triggered when a carousel is initialized.
carousel.next Triggered when next function is triggered.
carousel.prev Triggered when prev function is triggered.
carousel.slide When slide is triggered.
carousel.slide.end Triggered when the animation of slide is complete.
Parameters:
Name Type Argument Description
el HTMLElement

The carousel element.
settings Object <optional>

Configuration settings.

Properties
Name Type Argument Default Description
current Number <optional>
 0

The current slide to start on.
autoplay Boolean <optional>
 false

The carousel will start automatically.
autoplaySpeed Number <optional>
 2000

The autoplay interval in milliseconds.
dots Boolean <optional>
 false

Dot navigation.
nav Boolean <optional>
 true

Arrow navigation.
arrowKeys Boolean <optional>
 false

Arrow keyboard navigation.
touch Boolean <optional>
 false

Swipe support.
infinite Boolean <optional>
 false

Infinte amount of slides.
cb function

Callback function after slide has animated.

Properties
Name Type Description
index Number

The current slide index.
el HTMLElement

The carousel element.
Examples

Sample carousel HTML (initialized via data- with default settings.):

<div class="carousel" id="customCarousel" data-carousel>
  <ul>
    <li class="carousel-slide"><span>0</span><img alt="" src="images/carousel-imgs/giraffe.jpg" /></li>
    <li class="carousel-slide"><span>1</span><img alt="" src="images/carousel-imgs/eagle.jpg" /></li>
    <li class="carousel-slide"><span>2</span><img alt="" src="images/carousel-imgs/elephant.jpg" /></li>
    <li class="carousel-slide"><span>3</span><img alt="" src="images/carousel-imgs/lion.jpg" /></li>
  </ul>
</div>

Rendered HTML with all settings.

<div class="carousel animals js-carousel-initialized" data-carousel="autoplay:true:dots:true:arrowKeys:true:infinite:true:current:1" tabindex="0">
  <div class="carousel-viewer" style="overflow: hidden;">
    <ul>
      <li class="carousel-slide"><span>3</span><img alt="" src="images/carousel-imgs/lion.jpg" /></li>
      <li class="carousel-slide"><span>0</span><img alt="" src="images/carousel-imgs/giraffe.jpg" /></li>
      <li class="carousel-slide"><span>1</span><img alt="" src="images/carousel-imgs/eagle.jpg" /></li>
      <li class="carousel-slide"><span>2</span><img alt="" src="images/carousel-imgs/elephant.jpg" /></li>
      <li class="carousel-slide"><span>3</span><img alt="" src="images/carousel-imgs/lion.jpg" /></li>
      <li class="carousel-slide"><span>0</span><img alt="" src="images/carousel-imgs/giraffe.jpg" /></li>
    </ul>
  </div>
  
  <a href="#" class="carousel-nav prev"><i>←</i> <span>Previous</span></a>
  <a href="#" class="carousel-nav next"><span>Next</span> <i>→</i></a>

  <div class="carousel-dots">
    <ul>
      <li class=""><a href="#" rel="0">•</a></li>
      <li class="active"><a href="#" rel="1">•</a></li>
      <li class=""><a href="#" rel="2">•</a></li>
      <li class=""><a href="#" rel="3">•</a></li>
    </ul>
  </div>
</div>

Initializing carousel via JavaScript

var carousel = new ML.Carousel(ML.El.$q('#initCarousel'), {
  dots: true,
  arrowKeys: true,
  infinite: true
}, function(index, el) {
  // Slide complete function. 
  // index = current slide index. el = carousel element.
  console.log(index, el);
});

Referencing carousel object in JavaScript.

<div class="carousel" id="customCarousel" data-carousel>
  ...
</div>

<button id="carouselNext">Next button</button>

<script>
  var carousel = ML.El.$q('#customCarousel').MLCarousel;
  
  carousel.complete(function(index, el) {
    console.log(index, el);
  });
  
  ML.El.evt(ML.El.$q('carouselNext'), 'click', function(e) {
    carousel.next();
  });
</script>

Using custom events.

document.addEventListener('carousel.next', function(event) {
   var eventDetails = event.detail;
   console.log('carousel next slide', eventDetails.carousel);
   console.log('carousel options', eventDetails.options);
});

Methods

autoplay(start)

Toggle autoplay.

Parameters:
Name Type Description
start Boolean

Starts or stops autoplay.

destroy()

Destroys instance of the carousel.

goTo(index)

Goes to a specific slide.

Parameters:
Name Type Description
index Number

The slide index.

init()

Initializes the carousel.

next()

Show the next slide.

prev()

Show the previous slide.