embla-carousel-angular v14.1.0

npm i embla-carousel-angular

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

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;
}

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

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

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