Basic carousel engine on Angular
https://vagrantai-c.github.io/ng-carousel-cdk/
Current major version of Angular. Package might work on Angular version 9 or higher, but not guaranteed
npm i ng-carousel-cdk
-
Import carousel in module
import { CarouselModule } from 'ng-carousel-cdk'; @NgModule({ imports: [ CarouselModule, ], }) export class AnyModule { }
-
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
Selector: ng-carousel
Exported as ngCarousel
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 tongCarouselSlide
inputitemIndex
: item index of current slideisActive
: whether slide is currently activeinViewport
: whether slide is currently visible (at least 1 pixel is in viewport)activeOnTheLeft
: whether active slide is currently to the left of the current oneactiveOnTheRight
: 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
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
anditems$
are present, firstitems
would be used synchronously and then there would be a subscription toitems$
. -
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
%
orvw
). -
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 changemaxIndex
- items array length - 1callback result - new item index that should be applied, defaults to 0. Would clamp between 0 and
maxIndex
if overflows
itemIndexChange
Emits number of item index upon active slide changes
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 slidecarouselRef.prev()
: decrement active slidecarouselRef.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 whenshouldRecalculateOnResize
is turned off and carousel width mode isCarouselWidthMode.PX
(pixels).carouselRef.slideIndex
: returns current active slide index, might be useful for composing paginatorscarouselRef.items
: returns unwrapped set of items. It might be helpful to syncrhonously obtain list of items whenitems$
config field is used
selector: [ngCarouselPreventGhostClick]
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.
<!-- Put element selector on draggable containers -->
<ul #dragContainer>
<!-- Carousel slide -->
<li>
<!-- Interactive element -->
<a
[ngCarouselPreventGhostClick]="dragContainer"
href="...">
...
</a>
</li>
</ul>