ng-carousel-cdk

ng-carousel-cdk

Basic carousel engine on Angular

Demo

https://vagrantai-c.github.io/ng-carousel-cdk/

Requirements

Angular version 7 or higher

Install

npm i ng-carousel-cdk

Usage

1. Import carousel in module

   import { CarouselModule } from 'ng-carousel-cdk';
   
   @NgModule({
       imports: [
           CarouselModule,
       ],
   })
   export class AnyModule { }
   

2. Apply it in component

   Component:

   interface CarouselItem {
       name: number;
   }
   
   ...
   
   const config: CarouselConfig<CarouselItem> = {
       items: [
           {name: 1},
           {name: 2},
           {name: 3},
       ],
   }
   

   Template:

   <ng-carousel
       #carouselRef="ngCarousel"
       [config]="config">
       <ng-template
           [ngCarouselSlide]="carouselRef"
           let-item>
           {{item.name}}
       </ng-template>
   </ng-carousel>
   

Providing a carousel reference to ngCarouselSlide is optional, but gives a type defense for $implicit variable

API

CarouselComponent

Selector: ng-carousel

Exported as ngCarousel

Slide declaration

Use template with ngCarouselSlide directive applied to declare slide template. Every item provided within carousel config would be injected into it. Example:

<ng-carousel>
    <ng-template
        ngCarouselSlide
        let-item
        let-index="itemIndex"
        let-isActive="isActive"
        let-inViewport="inViewport">
        Slide №{{index}} content
    </ng-template>
</ng-carousel>

Template is enriched with next context structure:

• $implicit: injected item, would have correct type if carousel reference is provided to ngCarouselSlide input
• itemIndex: item index of current slide
• isActive: whether slide is currently active
• inViewport: whether slide is currently visible (at least 1 pixel is in viewport)
• activeOnTheLeft: whether active slide is currently to the left of the current one
• activeOnTheRight: whether active slide is currently to the right of the current one

Template variables can (and should) be typed with carousel input:

readonly config: CarouselConfig<number> = {
    ...,
    items: [1, 2, 3],
}

<ng-carousel
    #carouselRef="ngCarousel"
    [config]="config">
    <ng-template
        [ngCarouselSlide]="carouselRef"
        let-item>
        Slide №{{index}} content
    </ng-template>
</ng-carousel>

item ng-template variable would have a correct type of number

Inputs

config: CarouselConfig

Possible options:

• items: T[] = [];
  

  Items to be rendered inside carousel.

• slideWidth = 100;
  

  All slides have same width and this field specifies it.

• widthMode: CarouselWidthMode = CarouselWidthMode.PERCENT;
  

  How slideWidth should interpret its value, whether in pixels or percents.

• alignMode: CarouselAlignMode = CarouselAlignMode.CENTER;
  

  Regulates where active slide should be place.

• autoplayEnabled = true;
  

  Whether active slide should change over time/

• autoplayDelay = 6000;
  

  Specifies how often active slide should change. Only applied if autoplayEnabled is set to true.

• dragEnabled = true;
  

  Whether drag is enabled.

• shouldLoop = true;
  

  Whether carousel is allowed to copy slides in order to fill empty space.

• transitionDuration = 280;
  

  Animation duration on slide change.

• shouldRecalculateOnResize = true;
  

  Whether carousel should recalculate upon window resize. Useful when carousel takes full page width or carousel width is relative to viewport width (either in % or vw).

• recalculateDebounce = 300;
  

  Specifies time for which carousel would wait after resize event to recalculate its positions. 0 means no debounce is applied.

Outputs

itemIndexChange

Emits number of item index upon active slide changes

API

One can export carousel via exportAs or @ViewChild syntax.

Template

<ng-carousel #carouselRef="ngCarousel"></ng-carousel>

or

@ViewChild(CarouselComponent) carouselRef: CarouselComponent;

Use this reference to programmaticaly trigger next events:

• carouselRef.next(): increment active slide
• carouselRef.prev(): decrement active slide
• carouselRef.setIndex(newIndex: number): focus slide with provided item index. When no slides are available, index change would postpone till slide initialization.
• carouselRef.recalculate(): recalculate positions. Might be useful when shouldRecalculateOnResize is turned off and carousel width mode is CarouselWidthMode.PX (pixels).
• carouselRef.slideIndex: returns current active slide index, might be useful for composing paginators

PreventGhostClickDirective

selector: [ngCarouselPreventGhostClick]

Usage

Use directive on button, anchor or any clickable/draggable element. This will prevent ghost clicks after pan ends.

<ng-carousel>
    <button
        (click)="processClick($event)"
        ngCarouselPreventGhostClick>
        ...
    </button>
</ng-carousel>

When drag starts on button element, it won't be clicked upon drag end.

Changelog

1.8.1 (2021-12-01)

Bug Fixes

• allow ghost click directive to be used outside carousel (acd3e39)