embla-carousel

What is embla-carousel?

Embla Carousel is a lightweight, extendable, and customizable carousel library for modern web applications. It provides a simple API for creating responsive and touch-friendly carousels with various customization options.

What are embla-carousel's main functionalities?

Basic Carousel Setup

This code initializes a basic Embla Carousel on an HTML element with the class 'embla'.

const emblaNode = document.querySelector('.embla');
const embla = EmblaCarousel(emblaNode);

Custom Options

This code demonstrates how to initialize an Embla Carousel with custom options such as looping and speed.

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

Adding Plugins

This code shows how to add plugins to the Embla Carousel, such as the Autoplay plugin for automatic sliding.

import EmblaCarousel from 'embla-carousel';
import Autoplay from 'embla-carousel-autoplay';

const emblaNode = document.querySelector('.embla');
const embla = EmblaCarousel(emblaNode, { loop: true }, [Autoplay()]);

Event Handling

This code demonstrates how to handle events in Embla Carousel, such as logging the selected slide index when a slide is selected.

const emblaNode = document.querySelector('.embla');
const embla = EmblaCarousel(emblaNode);

embla.on('select', () => {
  console.log('Slide selected:', embla.selectedScrollSnap());
});

Other packages similar to embla-carousel

swiper

Swiper is a modern touch slider with hardware-accelerated transitions and a wide range of features. It is highly customizable and supports various effects, autoplay, and responsive breakpoints. Compared to Embla Carousel, Swiper offers more built-in features and effects but may be heavier in terms of bundle size.

slick-carousel

Slick Carousel is a popular and fully-featured carousel library that supports multiple breakpoints, lazy loading, and various transition effects. It is easy to set up and use but may not be as lightweight or modular as Embla Carousel.

react-slick

React Slick is a React wrapper for the Slick Carousel library. It provides the same features as Slick Carousel but is designed specifically for React applications. It offers a simple API for integrating carousels into React components. Compared to Embla Carousel, React Slick is more tailored for React but may not offer the same level of customization and modularity.

README

Embla Carousel

Extensible low level carousels for the web. Extend it with basic JavaScript and build awesome physics simulated carousels. Dependency free and 100% open source.

 TRY DEMO 

options   ·   api   ·   codesandbox

 

Installation

NPM

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

import EmblaCarousel from 'embla-carousel'

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 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()}

scrollProgress()

Returns how far the carousel has scrolled from 0 at the first slide to 1 at the end.

^{✨ Demo - embla.scrollProgress()}

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()}

CodeSandbox

Get started instantly with one of the CodeSandboxes below.

  Basic Setup - With Previous, Next & Dot buttons.

  Autoplay - Example of how to setup Autoplay.

Browser Support

Embla has been tested in the browsers listed below. Special thanks goes to BrowserStack.

  IE - 11

  Edge - Latest 2 versions

  Chrome - Latest 2 versions

  Firefox - Latest 2 versions

  Safari - Latest 2 versions

Contributors

Thank you to all contributors for making Embla Carousel awesome! Contributions are welcome.

Open Source

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

· · ·