Quick Start

Installation

First, install the core Embla Carousel package using your preferred package manager. Embla is dependency-free and lightweight.

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

HTML Structure

Embla Carousel requires a specific hierarchical structure consisting of a viewport, a container, and 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>

Required CSS

For the carousel to function correctly, you must apply minimal layout styles. The viewport needs to hide overflow, and the container must arrange slides in a row.

.embla {
  overflow: hidden;
}
.embla__container {
  display: flex;
}
.embla__slide {
  flex: 0 0 100%; /* Default to one slide per view */
  min-width: 0;
}

Initialization

Initialize the carousel by passing the viewport node and an optional options object to the EmblaCarousel constructor.

import EmblaCarousel from 'embla-carousel'

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

// The API is now ready
console.log(emblaApi.slideNodes()) 

Framework Wrappers

If you are using a specific framework, Embla provides dedicated wrappers to handle the lifecycle and refs for you:

• React: useEmblaCarousel
• Vue: useEmblaCarousel
• Svelte: useEmblaCarousel
• Solid: useEmblaCarousel

Each wrapper returns a ref (to be attached to the viewport) and the emblaApi instance for programmatic control.