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)