Embla Carousel

An extensible low level carousel for the web, written in TypeScript.

  DEMO PAGE  

«  OPTIONS   |   THE API  »

 

Installation

NPM

npm install embla-carousel

import EmblaCarousel from 'embla-carousel'

QuickStart

HTML

<div class="embla">
  <div class="embla__container">
    <div class="embla__slide">
      Slide 1
    </div>
    <div class="embla__slide">
      Slide 2
    </div>
    <div class="embla__slide">
      Slide 3
    </div>
  </div>
</div>

CSS

.embla {
  overflow: hidden;
}

.embla__container {
  display: flex;
}

.embla__slide {
  position: relative; /* Needed if loop: true */
  flex: 0 0 100%; /* Choose any width */
}

JavaScript

const emblaNode = document.querySelector('.embla')
const options = { loop: true }
const embla = EmblaCarousel(emblaNode, options)

Options

Configure Embla by passing an options object as the second argument. Default options values are:

const embla = EmblaCarousel(emblaNode, {
  align: 'center',
  containerSelector: '*',
  slidesToScroll: 1,
  containScroll: false,
  draggable: true,
  dragFree: false,
  loop: false,
  speed: 10,
  startIndex: 0,
  selectedClass: 'is-selected',
  draggableClass: 'is-draggable',
  draggingClass: 'is-dragging',
})

align   ^{type: string}

Align the slides relative to the carousel viewport.

^{✨ Demo - start · center · end}

containerSelector   ^{type: string}

A query selector for the container that holds the slides, where all immediate children will be treated as slides.

^{✨ Demo - * · .my-classname}

slidesToScroll   ^{type: number}

Scrolls past given number of slides whether scroll is triggered by API methods or drag interactions.

^{✨ Demo - 1 · 2}

containScroll   ^{type: boolean}

Contains slides to carousel viewport to prevent excessive scrolling at the beginning or end.

^{✨ Demo - false · true}

draggable   ^{type: boolean}

Allow mouse & touch interactions to scroll the carousel.

^{✨ Demo - true · false}

dragFree   ^{type: boolean}

Determines if the carousel should snap to a slide position after mouse & touch interactions.

^{✨ Demo - false · true}

loop   ^{type: boolean}

Determines if the carousel should loop when start or end is reached.

^{✨ Demo - false · true}

speed   ^{type: number}

Carousel speed when using API methods to navigate. A higher number will make transitions faster.

^{✨ Demo - 10 · 15}

startIndex   ^{type: number}

Zero based index of the starting slide when carousel mounts.

^{✨ Demo - 0 · 3}

selectedClass   ^{type: string}

Classname that will be applied to the selected slide.

^{✨ Demo - is-selected · my-class}

draggableClass   ^{type: string}

Classname that will be applied to the wrapper when the carousel mounts if draggable.

^{✨ Demo - is-draggable · my-class}

draggingClass   ^{type: string}

Classname that will be applied to the wrapper when a pointer is dragging the carousel.

^{✨ Demo - is-dragging · my-class}

API

Embla exposes API methods that can be used to control the carousel externally. Example usage:

embla.scrollNext()
embla.scrollTo(2)
embla.changeOptions({ loop: true })
embla.on('select', () => {
  console.log(`Selected snap index is ${embla.selectedScrollSnap()}!`)
})

containerNode()

Returns the current container element node.

^{✨ Demo - embla.containerNode()}

slideNodes()

Returns the slides as an array of element nodes.

^{✨ Demo - embla.slideNodes()}

scrollNext()

Scrolls to next snap point if possible. If loop: false and the carousel is on the last snap point this method will do nothing.

^{✨ Demo - embla.scrollNext()}

scrollPrev()

Scrolls to previous snap point if possible. If loop: false and the carousel is on the first snap point this method will do nothing.

^{✨ Demo - embla.scrollPrev()}

scrollTo(index)

Scrolls to the snap point that matches the passed index. If loop: true the carousel will seek the closest way to the target.

^{✨ Demo - embla.scrollTo()}

canScrollPrev()

Returns if it's possible to scroll to a previous snap point. If loop: true this will always return true.

^{✨ Demo - embla.canScrollPrev()}

canScrollNext()

Returns if it's possible to scroll to a next snap point. If loop: true this will always return true.

^{✨ Demo - embla.canScrollNext()}

selectedScrollSnap()

Returns the index of the selected snap point. Each snap point scrolls more than one slide if slidesToScroll > 1. Zero-based.

^{✨ Demo - embla.selectedScrollSnap()}

previousScrollSnap()

Returns the index of the previous snap point. Each snap point scrolls more than one slide if slidesToScroll > 1. Zero-based.

^{✨ Demo - embla.previousScrollSnap()}

scrollSnapList()

Returns an array of all scroll snap points, each containing slide numbers and slide nodes.

^{✨ Demo - embla.scrollSnapList()}

changeOptions(options)

Applies passed options by doing all the necessary calculations and initialising the carousel from scratch.

^{✨ Demo - embla.changeOptions()}

on(event, callback)

Subscribes to a custom Embla event by firing the passed callback. Below is a list of events you can subscribe to:

• init - When the carousel has been initialised for the first time.
• destroy - When the carousel has been destroyed.
• select - When a new target slide has been selected.
• scroll - When carousel is scrolled.
• resize - When window size changes.
• dragStart - When carousel dragging begins.
• dragEnd - When carousel dragging ends.

^{✨ Demo - embla.on()}

off(event, callback)

Ends subscription to a custom Embla event by removing the passed callback. This works for all events listed on the on method.

^{✨ Demo - embla.off()}

destroy()

Removes all styles applied to DOM nodes and kills all event listeners for this Embla instance.

^{✨ Demo - embla.destroy()}

Browser Support

•   IE - 11

•   Edge - Latest 2 versions

•   Chrome - Latest 2 versions

•   Firefox - Latest 2 versions

•   Safari - Latest 2 versions

Open Source

^{Copyright © 2019-present, David Cetinkaya.}
Embla is MIT licensed 💖

📋 contribution