@ncremental/carousel

Angular Carousel Component

An Angular carousel component with SSR support by Ncremental.

Installation

Simply run:

npm i @ncremental/carousel

Usage

First, add the component to your module:

import { NcrCarouselModule } from '@ncremental/carousel';

@NgModule({
  imports: [NcrCarouselModule]
})
export class MyModule {}

Then, use it in your component's HTML:

<ncr-carousel
  class="carousel carousel-xs-1 carousel-md-4 carousel-lg-4"
  [items]="items$ | async"
  [template]="carouselItem"
  [configuration]="{ autoplayDelay: 1000, visibleCount: { xs: 1, sm: 1, md: 4, lg: 4, xl: 4 } }"
>
</ncr-carousel>

<ng-template #carouselItem let-item$="item">
  <!-- Your slide template -->
</ng-template>

Configuration

The following properties can be set on the configuration object:

interface CarouselConfig {
  visibleCount: {
    xs: number;
    sm?: number;
    md?: number;
    lg?: number;
    xl?: number;
    xxl?: number;
  };
  touchEnabled?: boolean;
  touchEnabledDesktop?: boolean;
  autoplayDelay?: number;
  controls?: boolean;
  indicators?: boolean;
  moveBy?: number;
  loop?: boolean;
  lazyLoadIncrement?: number;
  ssrItemsToLoad?: number;
  dragThreshold?: number;
  templates?: {
    prevControl?: TemplateRef<any>;
    nextControl?: TemplateRef<any>;
    indicators?: TemplateRef<any>;
  };
  labels?: {
    prevControl?: string;
    nextControl?: string;
    indicators?: string;
  };
}

Linking Carousels

You can easily link different carousels with each other using our public observables and methods.

Thumbnails

Let's say you want a second carousel which shows thumbnails of your slides. You can simply create an observable which keeps track of the active UID:

activeUID$ = new BehaviorSubject(0);

Then, you need to sync the two carousels:

function syncCarousels(mainCarousel: NcrCarouselComponent, thumbCarousel: NcrCarouselComponent) {
  // Update UID on main carousel navigation
  mainCarousel.currentPage$.pipe(takeUntil(this.destroyed$)).subscribe((page) => this.activeUID$.next(page));
  // Sync carousels when UID changes
  this.activeUID$.pipe(takeUntil(this.destroyed$)).subscribe((page) => {
    mainCarousel.activePage = page;
    thumbCarousel.activePage = page;
  });
}

In your template you can add a click event which jumps to a specific slide when it is clicked:

<ng-template #thumbItem let-item="item" let-uid="uid">
  <a
    tabindex="0"
    (click)="activeUID$.next(uid)"
    [class]="activeUID$.getValue() === uid ? 'active-slide' : ''"
  >
    <img [src]="$any(item).img" width="100" loading="lazy" />
  </a>
</ng-template>

Autoplay Pause

You can control the autoplay functionality of the carousel using the autoplayPause input and listen for changes with the autoplayPauseChange output.

Using autoplayPause input

To pause the autoplay, set the autoplayPause input to true. To resume, set it to false:

<ncr-carousel
  class="carousel carousel-xs-1 carousel-md-4 carousel-lg-4"
  [items]="items$ | async"
  [template]="carouselItem"
  [configuration]="{ autoplayDelay: 1000, visibleCount: { xs: 1, sm: 1, md: 4, lg: 4, xl: 4 } }"
  [autoplayPause]="isAutoplayPaused"
>
</ncr-carousel>

In your component class:

import { Component } from '@angular/core';

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html',
  styleUrls: ['./your-component.component.css']
})
export class YourComponent {
  isAutoplayPaused: boolean = false;

  // Your button onClick
  toggleAutoplay() {
    this.isAutoplayPaused = !this.isAutoplayPaused;
  }
}

Listening to Autoplay Changes

If you want to listen to changes on autoplay that come from the carousel, just listen for the (autoplayPauseChange) output value emitted and set your current value to true/false:

<ncr-carousel
  class="carousel carousel-xs-1 carousel-md-4 carousel-lg-4"
  [items]="items$ | async"
  [template]="carouselItem"
  [configuration]="{ autoplayDelay: 1000, visibleCount: { xs: 1, sm: 1, md: 4, lg: 4, xl: 4 } }"
  [autoplayPause]="isPaused"
  (autoplayPauseChange)="handleAutoplayPause($event)"
>
</ncr-carousel>

In your component class:

import { Component } from '@angular/core';

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html',
  styleUrls: ['./your-component.component.css']
})
export class YourComponent {
  isAutoplayPaused: boolean = false;

  // Your button onClick
  toggleAutoplay() {
    this.isAutoplayPaused = !this.isAutoplayPaused;
  }
  
  handleAutoplayPause(state: boolean) {
    this.isAutoplayPaused = state;
  }
}

Try it locally

If you want to try it locally. Run in spartacus-extensions:

yarn build:carousel

Then in the package.json of the project you want to try the carousel updated :

"@ncremental/carousel": "file:/path/to/spartacus-extensions/dist/ncr-carousel"