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

« View Demo »

• What's Embla?
• Implementations
• Features
• Installation
• QuickStart
• Options
• API
• Browser Support
• Contribution
• License

Embla’s purpose is to provide a low level carousel and allow developers to extend it by using its available methods. Extend it with some basic JavaScript and build awesome physics simulated carousels. It’s dependency free and 100% open source.

Try it on the Demo Page or CodeSandbox ✨.

• Responsive out of the box - Choose any %-based slide widths.
• Seamless loop effect - No pauses or previous/next button throttling.
• Hardware accelerated - Smooth physics simulated animations.
• Extensible rich API - Comes with a low-level API to control the carousel.
• Realistic drag handling - Authentic cross device drag behaviour.

If you are using a module bundler...

yarn add embla-carousel

import EmblaCarousel from 'embla-carousel'

...or manually inject this script into your website.

<script src="embla.min.js"></script>

Setup your HTML markup...

<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>

...add some CSS...

.embla {
  overflow: hidden;
}

.embla__container {
  display: flex;
  will-change: transform;
}

.embla__slide {
  position: relative;
  flex: 0 0 auto;
  width: 100%;
}

...initialize the script and pass the element node...

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

...and you're good to go!

Embla comes with a few optional settings that you can change by passing an object as the second argument. Default values are:

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

align (string: start | center | end)
Align the slides relative to the carousel viewport.

containerSelector (string: querySelectorString)
The selector to use for the container that holds the slides. Embla will use all immediate children of this node as slides.

slidesToScroll (number)
Scrolls past given number of slides whether scroll is triggered by next(), previous or goTo() methods as well as drag interactions.

draggable (boolean)
Allow mouse and touch interactions to move the carousel.

dragFree (boolean)
Determines if the carousel should snap to a slide position after mouse and touch interactions.

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

speed (number: 5 - 20)
Carousel speed when using buttons to navigate. A higher number will make transitions faster. Pointer events are not affected by this.

startIndex (number)
Zero based index of the starting slide when carousel mounts.

selectedClass (string)
Classname that will be applied to the selected slide.

draggableClass (string)
Classname that will be applied to the wrapper when the carousel mounts if draggable: true.

draggingClass (string)
Classname that will be applied to the wrapper when a pointer is dragging the carousel.

Embla exposes a set of methods upon setup that can be used to control the carousel externally. Example usage looks like this:

embla.next()
embla.goTo(2)
embla.changeOptions({ loop: true })
embla.on('select', () => {
  console.log(`Selected index is now ${embla.selectedIndex()}!`)
})

...and the methods are:

containerNode()
Returns the current container element node.

slideNodes()
Returns the slides as an array of element nodes.

next()
Moves to next item. If loop: false and the carousel is on the last slide this method will do nothing.

previous()
Moves to previous item. If loop: false and the carousel is on the first slide this method will do nothing.

goTo(index: number)
Moves to item that matches passed index. If loop: true the carousel will seek the closest way to the passed index.

selectedIndex()
Returns the current selected index. Each index contains multiple slides if slidesToScroll > 1. If slidesToScroll: 1 each slide has its own index. Zero-based.

previousIndex()
Returns the previous selected index. Each index contains multiple slides if slidesToScroll: > 1. If slidesToScroll: 1 each slide has its own index. Zero-based.

groupedIndexes()
Returns an array of all slide indexes grouped into arrays according to the slidesToScroll option, i.e. if the total number of slides is 4 and slidesToScroll: 2, it will return [[0, 1], [2, 3]].

canScrollPrevious()
Returns if it's possible to scroll to previous from here. Note that if loop: true this will always return true.

canScrollNext()
Returns if it's possible to scroll to next from here. Note that if loop: true this will always return true.

changeOptions(options: options)
Applies passed options by doing all the necessary calculations and reinitialising the carousel from scratch.

on(event: string, callback: function)
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.
• resize - When window size changes.
• dragStart - When carousel dragging begins.
• dragEnd - When carousel dragging ends.

off(event: string, callback: function)
Ends subscription to a custom Embla event by removing the passed callback. This works for all events listed on the on method.

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

•   IE - 11

•   Edge - Latest 2 versions

•   Chrome - Latest 2 versions

•   Firefox - Latest 2 versions

•   Safari - Latest 2 versions

Thank you to all the people who already contributed to Embla Carousel 🙏!
Do you like this project and want to contribute to it?

• I just want to support it: Thank you! Give it a star maybe ⭐?
• I want to spread the word: You're a star! Why not twitter or similar 📣?
• I want to get my hands dirty: Awesome! Read the contribution guidelines first 📋.

Embla is MIT licensed.
Copyright © 2019-present, David Cetinkaya.