A lightweight carousel UI for Angular, support mobile touch with Hammerjs.
Work with custom animation, and server-side-rendering.
An Carousel that easy to use with your custom template.
This package is design by angular and hammerjs.
Depend on Hammerjs.
Support Angular 18+ please use v18.x.x version, which follow the main version of Angular.
for version before v18, please use v3.0.0, view more legacy version in legacy readme.
npm install --save ngx-hm-carousel hammerjsimport 'hammerjs';
import { provideExperimentalZonelessChangeDetection, model } from '@angular/core';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { NgxHmCarouselComponent, NgxHmCarouselDynamicDirective, NgxHmCarouselItemDirective } from './lib';
import { NgClass, NgFor } from '@angular/common';
import { FormsModule } from '@angular/forms';
@Component({
selector: 'app-root',
standalone: true,
imports: [NgxHmCarouselComponent, NgxHmCarouselItemDirective, NgxHmCarouselDynamicDirective, NgClass, FormsModule, NgFor],
templateUrl: './app.component.html',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class App {
currentIndex = model(0);
speed = 5000;
infinite = true;
direction = 'right';
directionToggle = true;
autoplay = true;
avatars = '1234567891234'.split('').map((x, i) => {
const num = i;
// const num = Math.floor(Math.random() * 1000);
return {
url: `https://picsum.photos/600/400/?${num}`,
title: `${num}`,
};
});
click(i: number) {
console.log(`${i}`);
}
}
bootstrapApplication(App, {
providers: [provideExperimentalZonelessChangeDetection()],
});app.component.html
<ngx-hm-carousel [(ngModel)]="currentIndex" [show-num]="4" [autoplay-speed]="speed" [infinite]="infinite" [drag-many]="true" [aniTime]="200" [data]="avatars" class="select-none">
<section ngx-hm-carousel-container class="flex">
<article class="transition-opacity duration-200 ease-linear py-2 px-1" ngx-hm-carousel-item *ngFor="let avatar of avatars; let i = index" [ngClass]="currentIndex() === i ? 'opacity-100' : 'opacity-50'">
<div class="h-96 bg-cover bg-center cursor-pointer" (click)="click(i)" [style.backgroundImage]="'url(' + avatar.url + ')'">{{ i }}</div>
</article>
<ng-template #infiniteContainer></ng-template>
</section>
<!-- only using in infinite mode or autoplay mode, that will render with-->
<ng-template #carouselContent let-avatar let-i="index">
<article class="transition-opacity duration-200 ease-linear py-2 px-1" [ngClass]="currentIndex() === i ? 'opacity-100' : 'opacity-50'">
<div class="h-96 bg-cover bg-center cursor-pointer" (click)="click(i)" [style.backgroundImage]="'url(' + avatar.url + ')'">{{ i }}</div>
</article>
</ng-template>
<ng-template #carouselPrev>
<div class="w-[50px] text-center">
<i class="material-icons text-3xl">keyboard_arrow_left</i>
</div>
</ng-template>
<ng-template #carouselNext>
<div class="w-[50px] text-center">
<i class="material-icons text-3xl">keyboard_arrow_right</i>
</div>
</ng-template>
<ng-template #carouselDot let-model>
<div class="size-2.5 opacity-50 rounded-full border-2 border-solid bg-blue-600" [ngClass]="{ 'opacity-100': model.index === model.currentIndex }"></div>
</ng-template>
<ng-template #carouselProgress let-progress>
<div class="progress"></div>
</ng-template>
</ngx-hm-carousel>| Attribute | Necessary | Default value | Type | Location | Description |
|---|---|---|---|---|---|
autoplay |
no | false | boolean |
ngx-hm-carousel | carousel auto play confing |
autoplay-speed |
no | 5000 (ms) | number |
ngx-hm-carousel | auto play speed |
between-delay |
no | 8000 (ms) | number |
ngx-hm-carousel | each auto play between time |
autoplay-direction |
no | 'right' | 'left' or 'right' |
ngx-hm-carousel | auto play direction |
mouse-enable |
no | false | boolean |
ngx-hm-carousel | is mouse moveover stop the auto play |
autoplay |
no | false | boolean |
ngx-hm-carousel | carousel auto play config |
[breakpoint] |
no | [] | NgxHmCarouselBreakPointUp |
ngx-hm-carousel | switch show number with own logic like bootstrap scss media-breakpoint-up |
show-num |
no | 1 | number or 'auto' |
ngx-hm-carousel | how many number items to show once |
scroll-num |
no | 1 | number |
ngx-hm-carousel | how many number with each scroll |
drag-many |
no | false | boolean |
ngx-hm-carousel | is can scroll many item once, simulate with scrollbar |
swipe-velocity |
no | 0.3 | number |
ngx-hm-carousel | Minimal velocity required before recognizing, unit is in px per ms. |
pan-boundary |
no | 0.15 | number of false |
ngx-hm-carousel | user move picture with the container width rate, when more than that rate, it will go to next or prev, set false will never move with distance rate |
align |
no | 'left' | 'left' or 'right' or 'center' |
ngx-hm-carousel | when show-num is bigger than 1, the first item align |
infinite |
no | false | boolean |
ngx-hm-carousel | is the carousel will move loop |
data |
no | undefined | any[] |
ngx-hm-carousel | the data you using with *ngFor, it need when infinite mode or autoplay mode |
aniTime |
no | 400 | number |
ngx-hm-carousel | when infinite is true, the animation time with item |
aniClass |
no | 'transition' | string |
ngx-hm-carousel | this class will add when carousel touch drag or click change index |
aniClassAuto |
no | 'aniClass' | string |
ngx-hm-carousel | this class will add when carousel auto play |
disable-drag |
no | false | boolean |
ngx-hm-carousel | disable drag event with touch and mouse pan moving |
not-follow-pan |
no | false | boolean |
ngx-hm-carousel | disable when drag occur the child element will follow touch point. |
[(ngModel)] |
no | 0 | number |
ngx-hm-carousel | You can bind ngModel with this carousel, it will two way binding with current index. You also can use (ngModelChange)="change($event)" with that. |
// the breakpoint interface
export interface NgxHmCarouselBreakPointUp {
width: number;
number: number;
}normal click with effect the touch event, using this event replace that.
| Attribute | Location | Description |
|---|---|---|
ngxHmCarouselDynamic |
any tag | It will dynamic load tag with element. |
This Directive will Dynamic load element with previous element and next element and current element.
- Example
<section ngx-hm-carousel-container class="content">
<article class="item cursor-pointer" ngx-hm-carousel-item *ngFor="let item of data; let i = index">
<div *ngxHmCarouselDynamic="i; length: data.length; index: currentI" class="img" [style.backgroundImage]="item.url"></div>
</article>
</section>- first data is this data index
- length is ths total length with array
- index is now index