Vanilla JavaScript

Introduction

Embla Carousel in its core form is a lightweight, dependency-free JavaScript library. To get started with the vanilla version, you only need a basic HTML structure and a few lines of JavaScript to initialize the carousel.

Installation

First, install the embla-carousel package using your preferred package manager:

npm install embla-carousel --save
# or
yarn add embla-carousel
# or
pnpm add embla-carousel

Alternatively, you can use a CDN like unpkg or jsDelivr directly in your HTML:

<script src="https://unpkg.com/embla-carousel/embla-carousel.umd.js"></script>

HTML Structure

Embla requires a specific hierarchical structure. By default, it looks for a viewport wrapper that contains a scroll container, which in turn holds the individual slides.

<div class="embla">
  <div class="embla__viewport">
    <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>
</div>

Initialization

To initialize the carousel, you pass the viewport node as the first argument to the EmblaCarousel constructor. You can also provide an optional object for configuration.

import EmblaCarousel from 'embla-carousel'

const viewportNode = document.querySelector('.embla__viewport')
const options = { loop: true }
const emblaApi = EmblaCarousel(viewportNode, options)

console.log(emblaApi.slideNodes()) // Access API methods

Styling

Embla Carousel does not provide default CSS for layout. You are responsible for styling the slides to sit side-by-side. A basic setup looks like this:

.embla {
  overflow: hidden;
}
.embla__container {
  display: flex;
}
.embla__slide {
  flex: 0 0 100%;
  min-width: 0;
}

Usage and API

The EmblaCarousel function returns an API object that allows you to control the carousel and listen to events.

Basic Controls

You can use the API to navigate programmatically:

const emblaApi = EmblaCarousel(viewportNode)

emblaApi.scrollNext()
emblaApi.scrollPrev()
emblaApi.scrollTo(2)

Listening to Events

Use the .on() method to react to carousel state changes, such as when a new slide is selected:

const logSelect = (emblaApi) => {
  console.log(`Selected snap index is ${emblaApi.selectedSnap()}`)
}

emblaApi.on('select', logSelect)

Adding Plugins

Plugins are passed as an array in the third argument of the constructor:

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

const emblaApi = EmblaCarousel(viewportNode, { loop: true }, [Autoplay()])

Cleanup

If you are building a Single Page Application (SPA) or need to remove the carousel manually, call the destroy method to clean up event listeners and internal logic:

emblaApi.destroy()

TypeScript Support

Embla Carousel is written in TypeScript and provides full type definitions. You can import the EmblaOptionsType or EmblaCarouselType for better developer experience:

import EmblaCarousel, { EmblaOptionsType, EmblaCarouselType } from 'embla-carousel'

const options: EmblaOptionsType = { loop: false }
const emblaApi: EmblaCarouselType = EmblaCarousel(viewportNode, options)