Skip to content

VagrantAI-c/ng-carousel-cdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

71d21bb · Jan 24, 2025
Jan 24, 2025
Mar 5, 2021
Jan 24, 2025
Jan 24, 2025
Aug 24, 2020
Jan 24, 2025
Dec 1, 2021
Apr 28, 2021
Jan 24, 2025
Aug 1, 2019
Jan 8, 2024
Jan 24, 2025
May 20, 2023
Jul 15, 2019
Jan 24, 2025
Jan 24, 2025
Jan 24, 2025
Jan 24, 2025
Jan 24, 2025
Mar 5, 2021
Mar 7, 2021

Repository files navigation

ng-carousel-cdk

Basic carousel engine on Angular

Demo

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

Requirements

Current major version of Angular. Package might work on Angular version 9 or higher, but not guaranteed

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 and their default values:

  • items: T[] = [];

    Items to be rendered inside carousel.

  • items$: Observable<T[]> = NEVER;

    Stream of items to be rendered inside carousel. If both items and items$ are present, first items would be used synchronously and then there would be a subscription to items$.

  • 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.

  • allowKeyboardNavigation = true;

    Whether carousel should listen to arrow keypresses and navigate to prev and next slide accordingly after left or right arrow key is pressed.

  • initialIndex: () => 0;

    Navigates carousel after initialization instantly to specified index. Might be enriched with callback argument to precisely restore previous index after config change, e.g.

    initialIndex: ({ currentItemIndex, maxIndex }) => currentItemIndex

    currentItemIndex - item index that was active at the time of the config change

    maxIndex - items array length - 1

    callback result - new item index that should be applied, defaults to 0. Would clamp between 0 and maxIndex if overflows

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
  • carouselRef.items: returns unwrapped set of items. It might be helpful to syncrhonously obtain list of items when items$ config field is used

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.

Usage on custom carousels

<!-- Put element selector on draggable containers -->
<ul #dragContainer>
    <!-- Carousel slide -->
    <li>
        <!-- Interactive element -->
        <a
            [ngCarouselPreventGhostClick]="dragContainer"
            href="...">
            ...
        </a>
    </li>
</ul>