cyberiumabc / carousel-library

ngx-carousel-ease is an Angular carousel library that aims to provide a simple, efficient, and practical carousel component.

ngx-carousel-ease

Description

ngx-carousel-ease is a versatile Angular library providing a feature-rich, simple, and performant carousel component. This library supports infinite and responsive mode, mouse and touch event. Attention has been put to accessibility, performance, and friendly developer experience.

Support Angular version starts at v17.

Demo

Live demonstration of the ngx-carousel-ease library here.

Installation

You can install the library using the following command:

npm i ngx-carousel-ease

Then, add the CarouselModule in the imports array of the hosting component (if standalone) or to your appModule. Finally, add your cards content within the <carousel></carousel> selector in the hosting component. Each of your card should contain the class carousel-slide.

<carousel>
  <div class="carousel-slide">
    ...
  </div>
  <div class="carousel-slide">
    ...
  </div>
  ...
</carousel>

Inputs

The carousel is configured by default and all inputs are optional.

Name	Default	Description
maxWidthCarousel	undefined	Define the max width of the carousel in pixels.
infinite	false	Enable infinite loop of slides.
responsive	true	Width of the slides will be automatically adapted. In non-responsive mode, the width of the slides won't be adapted.
autoSlide	true	Enable automatic sliding.
autoslideLimitPercentCard	30	Percentage of the card compared to mouvement to trigger automatic sliding.
slideToShow	3	Number of slides to show at a time. The number of slides to show is dependant of the available space.
slideToScroll	2	Number of slides to scroll at a time.
strechingLimit	60	Limit for the stretching effect in pixels. Streching effect occurs only in finite mode and at the start or end of the carousel.
slideWidth	300	Width of each slide in pixels.
slideMaxWidth	500	Maximum width of each slide in pixels.
dots	true	Display navigation dots.
arrows	true	Display navigation arrows.
counter	true	Display slide counter.
counterSeparator	'/'	Separator for the slide counter.
enableMouseDrag	true	Enable mouse drag for navigation.
enableTouch	true	Enable touch drag for navigation.
gapBetweenSlides	16	Gap between slides in pixels.
animationTimingFn	'ease-out'	Timing function for the slide transition animation. Options include 'linear', 'ease-in', 'ease-out', 'ease-in-out'.
animationTimingMs	300	Duration of slide transition animation in milliseconds.
maxDomSize	4	In infinite mode, maximum number of times the number of slides present in the DOM to prevent infinite growth. Example: 6 cards x 4 = 24 maximum cards. If you want to disable this feature, pass 'Infinity' to this property.

Service

This library provides a CarouselService containing an RxJs Subject onSlideChange that is triggered at every slide change. onSlideChange returns an object containing the current slide number and the carousel ID (useful if multiple carousel on a page to target a specific carousel instance). The slide number and carousel ID are zero indexed.

Inject the CarouselService through regular dependency injection in your hosting component.

ngOnInit() {
  this.carouselService.onSlideChange.subscribe((slideAndID) => {
    // change carousel colors, trigger a function, ...
  });
}

The third example in the demo uses this functionnality.

Style Customisation

Given the nearly infinite and subjective possibilities for customization, a predefined choice of themes (such as light or dark) has not been incorporated.

If you wish to customize the theme or parts of the carousel, add encapsulation: ViewEncapsulation.None to the hosting parent component and erase the default styles. Find the corresponding classes by inspecting the DOM.

The following example changes the defaulted blue arrows:

.carousel-container .prev,
.carousel-container .next {
  background: red !important;
}

SSR (Server Side Rendering)

This library supports Server Side Rendering (SSR). The carousel will not instantiate during server-side execution, as it requires access to the DOM API, preventing errors.

DX Friendly

Ensuring a seamless Developer Experience (DX), basic validation is performed on the parameters passed to the carousel. An error is raised in case of abnormal parameters. Please note that common sense mistakes, such as passing a negative value for slide to show or a negative carousel max width, are not validated. This library has been meticulously documented.

Performance

Emphasis has been placed on performance, adopting ChangeDetectionStrategy.OnPush and utilizing translate3d instead of translateX. This choice aims to enable hardware acceleration in specific scenarios, which can contribute to a smoother and more efficient user experience. By default, if infinite mode is enabled, a function will prevent infinite DOM growth by removing invisible cards.

Change log

Version 0.0.7: Support for dynamically HTML generated content (ngFor, @for) for slide creation. Correction of a validation bug.

Version 0.0.9: Change in the behavior of the auto slide. Auto slide will now occur on drag stop (when the user releases the mouse), and will automatically slide towards the nearest slide based on the set threshold. Auto slide is set to true by default.

Report a Bug

Please provide a detailed description of the encountered bug, including your carousel configuration and the steps/actions that led to the issue. An accurate description will help me to reproduce the issue.