npm package: @ncremental/carousel
Description: An Angular carousel component with SSR support by Ncremental.
Latest version: 17.5.14

# 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:

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

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

Then, use it in your component's HTML:

```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:

```ts
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:

```ts
activeUID$ = new BehaviorSubject(0);
```

Then, you need to sync the two carousels:

```ts
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:

```html
<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:

```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 } }"
  [autoplayPause]="isAutoplayPaused"
>
</ncr-carousel>
```

In your component class:
```ts
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:

```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 } }"
  [autoplayPause]="isPaused"
  (autoplayPauseChange)="handleAutoplayPause($event)"
>
</ncr-carousel>
```

In your component class:

```ts
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"
```