@kinect-pro/ngp-carousel

Angular2 Carousel

This project for Angular 2+ (currently supported version 8+)

Library version	npm tag	Angular version
6.x	ng13	Angular 13
5.x	ng12	Angular 12
4.x	ng11	Angular 11
3.x	ng10	Angular 10
2.x	ng9	Angular 9
1.2.x	ng8	Angular 8

Source code of project with examples are available by this link: gitlab.com/pretty-angular-components/slider

Site with demos available here: prettyangular.kinect.pro

This project has based on several requirements: was required slider which would support html components with text (links), events bindings and which can slide up to right corner of last element. So it is main features, available by default.

Note 1: If you develop for IE / Edge browser, do not forget include all required polyfills, such as classlist.js and web-animations-js

Note 2: Please note, if you use images, you should assign the width or wrap them in 'div' tag with assigned width property. It required because resize sensor can't detect changing of size of image on load event. Alternatively - you need to manually run method 'reset()' on each 'onLoad' image event.

Features

Adding your own template

To create a carousel from elements, you must pass your template to the component. Elements can be either interconnected into a collection (for example, an array of users, an array of links to photos with descriptions), or independent (for example, a photo with a description + user data + product card). You are not limited in the choice of elements to display.

Using elements of different width

You can use elements with different width. Scrolling such items will work correctly for each item.

Infinite mod

You can use loop scrolling if you want the animation to last in a circle.

Custom styles

You can customize the scroll controllers to your liking, or disable them.

Custom animation

You can customize the duration, delay and animation type.

Auto animation

You can enable the auto-scrolling and pass the number of milliseconds that must elapse before the animation. Animation will be carried out in an automatic mode until it reaches the last element, or the user focuses on the carousel.

Installation

How to install

With npm

npm install @kinect-pro/ngp-carousel

With yarn

yarn add @kinect-pro/ngp-carousel

To install target version you can use tags ng8, ng9, ng10 etc:
npm install @kinect-pro/ngp-carousel@ng9

How setup

Add NgpCarouselModule and BrowserAnimationsModule module

app.module

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { NgpCarouselModule } from '@kinect-pro/ngp-carousel';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    NgpCarouselModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Add carousel component to template

app.component.html

<ngp-carousel>
  <ng-template *ngFor="let elem of elements" ngpCarouselItem>
    <div class="your-classes">
      <span>{{elem.name}}</span>
    </div>
  </ng-template>
</ngp-carousel>

Usage examples

app.component.ts

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

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  elements = [
    {name: 'Jenfirebreatha'}, {name: 'Brainsra'}, {name: 'Pacoffin'}, {name: 'Quatorifiliny'},
    {name: 'Rosepop'}, {name: 'Agamason'}, {name: 'Mooreconda'}, {name: 'Hayetwinkle'}
  ];

  images = ['1.jpg', '2.jpg', '3.jpg', '4.jpg'];
}

app.component.html

1 Default carousel

<ngp-carousel>
  <ng-template *ngFor="let elem of elements" ngpCarouselItem>
    <div class="elem-item border border-dark text-center">
      <span>{{elem.name}}</span>
    </div>
  </ng-template>
</ngp-carousel>

2. Custom buttons

You can add your own styled buttons by using ngpCarouselButton directive and property slot (allowed values left or right) that decide on what place set your control.

<ngp-carousel>
  <ng-template *ngFor="let elem of elements" ngpCarouselItem>
    <div class="elem-item border border-dark text-center">
      <span>{{elem.name}}</span>
    </div>
  </ng-template>
  <div style="padding: 5px" ngpCarouselButton slot="left">
    <button class="btn btn-primary">Left</button>
  </div>
  <div style="padding: 5px" ngpCarouselButton slot="right">
    <button class="btn btn-primary">Right</button>
  </div>
</ngp-carousel>

Carousel by default will add click event on your component. But if you wish avoid this behaviours, you cant set disableDefaultClick flag to false

<button class="btn btn-lg btn-link" ngpCarouselButton [disableDefaultClick]="true" slot="right" (click)="rightClick()">
  <fa-icon [icon]="faRight" [size]="'2x'"></fa-icon>
</button>

3. Full width items
By default carousel use own element width for display them. But sometimes needed to use fully carousel width items. To achieve that you can use flag perPage set to true

<ngp-carousel [perPage]="true"
            [innerButtons]="true"
            [loop]="true"
            [animationDelay]="100"
            [animationDuration]="500"
            [animationEasing]="'ease-in-out'"
>
  <ng-template *ngFor="let img of images" ngpCarouselItem>
    <img src="assets/images/{{img}}" class="img-thumbnail">
  </ng-template>
</ngp-carousel>

More examples you can find on official homepage of project.

Properties

Property	Type	Default	Description
index	number	0	Only for reading. Returns index of current template item that carousel cursor is pointed.
isOnStart	boolean	true	Only for reading. returns `true` when carousel cursor positioned on first of templates.
isOnEnd	boolean	false	Only for reading. returns `true` when carousel cursor positioned on last of templates.
disabled	boolean	false	disable carousel activity.
loop	boolean	false	loop scrolling, the animation will to last in a circle.
rtl	boolean	false	right to lest carousel items orientation.
fullSizeItems	boolean	false	Makes items sized on full width of carousel container. *has removed since of version 2.1.0
perPage	boolean | number	false	Makes items seized on full or partial width of carousel container. *has added in version 2.1.0
buttonsMode	string | enControlsMode	'show'	Button display mode. Possible values: 'show' - always display 'hide' - always hidden 'auto' - will display buttons if width of content smaller than width of carouses
innerButtons	boolean	false	Flag allow to switch position where to place buttons, on the sides of carousel contend or on top of.
autoSlide	number | boolean	false	Time to automatic slide items in ms.
autoSlideDirection	string | enDirection	'next'	Direction of automatic slide items. Possible values: 'next' - slide to next item 'prev' - slide to previous item
animationDelay	number	0
animationDuration	number	250
animationEasing	string	'ease-in'

Methods

You can manipulate carousel manually by using @ViewChild()
Methods:
fill() - manual fill carousel by content items clear() - remove all carousel items prev() - move items to previous
next() - move items to next
toStart() - slide to first. working only when loop mode disabled
toEnd() - slide to last. working only when loop mode disabled

Events

You can subscribe on two event emitters:
animStart: - emit boolean value when animation is started
animFinish: - emit boolean value when animation is finished