Skip to content

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

Notifications You must be signed in to change notification settings

GreenFlag31/carousel-library

Repository files navigation

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

Installation

Version Command Description
V17 npm i [email protected] Install the V17 compatible version.
V18 npm i ngx-carousel-ease Install the V18 compatible version. This version is compatible with a zoneless Angular application.

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 sliding on drag stop. Carousel will slide towards the nearest slide.
autoslideLimitPercentCard 30 Percentage of the card compared to mouvement to trigger automatic sliding.
autoPlay false Enable automatic sliding within an interval of time. In finite carousel, autoPlay will stop if the start or the end of the carousel is reached.
autoPlayInterval 1500 Interval of time in milliseconds for automatic sliding (autoPlay).
autoPlayAtStart false Enable autoPlay at start.
autoPlaySlideToScroll 1 Number of slides to scroll for the autoPlay.
displayAutoPlayControls true Display the play and pause autoPlay controls.
playDirection ltr Direction of the autoPlay. Accepts: ltr or rtl (left to right or right to left).
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.

Version 0.1.1: Fixed a race condition that could occur betweeen evaluation of the template and initialisation of the variables.

Version 0.1.2: Adding an autoPlay feature.

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.

Ngx-ease serie

You like this library? Discover the ngx-ease serie here.

About

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

Topics

Resources

Stars

Watchers

Forks