README.md

Embla Carousel Angular

An Angular wrapper for Embla Carousel.

Installation

npm i embla-carousel-angular

The component structure

Embla Carousel provides the handy EmblaCarouselDirective standalone directive for seamless integration with Angular. A minimal setup requires an overflow wrapper and a scroll container. Start by adding the following structure to your carousel:

import { AfterViewInit, Component, ViewChild } from '@angular/core'
import {
  EmblaCarouselDirective,
  EmblaCarouselType
} from 'embla-carousel-angular'

@Component({
  selector: 'app-carousel',
  template: `
    <div class="embla" emblaCarousel [options]="options">
      <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>
  `,
  imports: [EmblaCarouselDirective],
  standalone: true
})
export class CarouselComponent implements AfterViewInit {
  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective

  private emblaApi?: EmblaCarouselType
  private options = { loop: false }

  ngAfterViewInit() {
    this.emblaApi = this.emblaRef.emblaApi
  }
}

Styling the carousel

The element with the classname embla is needed to cover the scroll overflow. Its child element with the container classname is the scroll body that scrolls the slides. Continue by adding the following CSS to these elements:

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

Accessing the carousel API

The emblaCarousel directive takes the Embla Carousel options as part of its inputs. Additionally, you can access the API by using the @ViewChild decorator to access the carousel in AfterViewInit hook。

Warning

Calling the following embla APIs directly will trigger too much ChangeDetection, which will lead to serious performance issues.

• emblaApi.on()
• emblaApi.scrollNext()
• emblaApi.scrollPrev()
• emblaApi.scrollTo()

Consider using the following methods which are wrapped with ngZone.runOutsideAngular():

• EmblaCarouselDirective.scrollPrev()
• EmblaCarouselDirective.scrollNext()
• EmblaCarouselDirective.scrollTo()

import { AfterViewInit, Component, ViewChild } from '@angular/core'
import {
  EmblaCarouselDirective,
  EmblaCarouselType
} from 'embla-carousel-angular'

@Component({
  selector: 'app-carousel',
  template: `
    <div class="embla" emblaCarousel [options]="options">
      <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>
  `,
  imports: [EmblaCarouselDirective],
  standalone: true
})
export class CarouselComponent implements AfterViewInit {
  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective

  private emblaApi?: EmblaCarouselType
  private options = { loop: false }

  ngAfterViewInit() {
    this.emblaApi = this.emblaRef.emblaApi
  }
}

Listening the carousel events

The emblaCarousel directive also provides a custom event: emblaChange that forwards embla events, also wrapped in ngZone.runOutsideAngular. You need to listen by passing the specified event names into subscribeToEvents input on demand.

import { AfterViewInit, Component, ViewChild } from '@angular/core'
import {
  EmblaCarouselDirective,
  EmblaCarouselType,
  EmblaEventType
} from 'embla-carousel-angular'

@Component({
  selector: 'app-carousel',
  template: `
    <div
      class="embla"
      emblaCarousel
      [options]="options"
      [subscribeToEvents]="subscribeToEvents"
      (emblaChange)="onEmblaChange($event)"
    >
      <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>
  `,
  imports: [EmblaCarouselDirective],
  standalone: true
})
export class CarouselComponent implements AfterViewInit {
  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective

  private emblaApi?: EmblaCarouselType
  private options = { loop: false }

  public readonly subscribeToEvents: EmblaEventType[] = [
    'init',
    'pointerDown',
    'pointerUp',
    'slidesChanged',
    'slidesInView',
    'select',
    'settle',
    'destroy',
    'reInit',
    'resize',
    'scroll'
  ]

  onEmblaChanged(event: EmblaEventType): void {
    console.log(`Embla event triggered: ${event}`)
  }

  ngAfterViewInit() {
    this.emblaApi = this.emblaRef.emblaApi
  }
}

Adding plugins

Start by installing the plugin you want to use. In this example, we're going to install the Autoplay plugin:

npm install embla-carousel-autoplay --save

The emblaCarousel directive inputs also accepts plugins. Note that plugins need to be passed in an array like so:

import { AfterViewInit, Component, ViewChild } from '@angular/core'
import {
  EmblaCarouselDirective,
  EmblaCarouselType
} from 'embla-carousel-angular'
import Autoplay from 'embla-carousel-autoplay'

@Component({
  selector: 'app-carousel',
  template: `
    <div class="embla" emblaCarousel [options]="options" [plugins]="plugins">
      <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>
  `,
  imports: [EmblaCarouselDirective],
  standalone: true
})
export class CarouselComponent implements AfterViewInit {
  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective

  private emblaApi?: EmblaCarouselType
  public options = { loop: false }
  public plugins = [Autoplay()]

  ngAfterViewInit() {
    this.emblaApi = this.emblaRef.emblaApi
  }
}

Thanks

Thanks to davidjerleke, zip-fa and JeanMeche for the review and advice.