@cristiansarghe/ng-generic-carousel

Generic Angular Carousel Component

What is it?

@cristiansarghe/ng-generic-carousel is a lightweight, mobile device friendly Angular carousel component made for ANY type of content, NOT only images.

Changelog

Version 3.0.0

• Angular 12 support
• Added drag-drop navigation support for mouse and touch inputs (HammerJS is a new dependency)
• Changed navigation button hiding logic (includes changes to Input() parameters)

Version 2.0.0

• Updated package to Angular 12
• Added round navigation option (when reaching the left or right side of the elements list, continue from the other side)

Installation

npm i @cristiansarghe/ng-generic-carousel

Basic usage

The component works by having a HTML template passed, along with an array of elements. By default, the component shows 3 elements at once.

<ng-generic-carousel [elements]="['John', 'Joanne', 'Jason', 'Jessica']">
	<ng-template #contentTemplate let-data="data">
		<p>I am {{data}}</p>
	</ng-template>

	<ng-template #leftButtonTemplate> &lt; </ng-template>
	<ng-template #rightButtonTemplate> &gt; </ng-template>
</ng-generic-carousel>

• ng-generic-carousel receives an array of objects or primitive values through @Input() elements.

• The component iterates through the array and repeats contentTemplate for each item.

• To access the current item you can target the data variable (let-data="data"), as presented above, and then use it within the template.

• For a more generic approach, leftButtonTemplate and rightButtonTemplate must be specified in order to customize the look of the left and right buttons.

Customization

Content

• The contentTemplate-named ng-template provides the layout for each carousel element.
• The leftButtonTemplate and rightButtonTemplate elements provide the content for the buttons (in order to customize the arrows as desired).
• @Input() visibleElementsCount changes the number of elements shown at once on the screen.
• NOTE: By default, if elements has less items than specified by visibleElementsCount, the left and right scroll buttons will NOT be shown. You can change this behavior by modifying @Input() hideNavigationButtonsWhenNotNeeded to false.
• In order to hide the navigation buttons at all times, set the hideNavigationButtons input to true. This usually works with the drag-drop navigation (see isDragDropEnabled input)

Example:

<ng-generic-carousel [elements]="['John', 'Joanne', 'Jason', 'Jessica']" [visibleElementsCount]="6" [hideNavigationButtons]="true" [isDragDropEnabled]="true">
	<ng-template #contentTemplate let-data="data">
		<p>I am {{data}}</p>
	</ng-template>

	<ng-template #leftButtonTemplate> &lt; </ng-template>			<!-- Will not be shown -->
	<ng-template #rightButtonTemplate> &gt; </ng-template>			<!-- Will not be shown -->
</ng-generic-carousel>

Placeholders

• The carousel can as well have placeholders that look all the same, with a layout provided in placeholderTemplate.
• The placeholders appear only if elements is null or empty.
• The number of placeholders is 3 by default, but can be changed using @Input() placeholderElementsCount.

<ng-generic-carousel [elements]="[]" [placeholderElementsCount]="4">
	<ng-template #contentTemplate let-data="data">
		<p>I am {{data}}</p>
	</ng-template>

	<ng-template #placeholderTemplate>
		<p>This will be a name!</p>
	</ng-template>

	<ng-template #leftButtonTemplate> &lt; </ng-template>
	<ng-template #rightButtonTemplate> &gt; </ng-template>
</ng-generic-carousel>

@Input()

Input	Type	Required	Description
elements	any[]	Optional, default: []	Array of objects or primitive values that represent each carousel item
placeholderElementsCount	number	Optional, default: 3	If placeholders are shown, this input sets how many placeholder elements to show
visibleElementsCount	number	Optional, default: 3	Number of visible elements at a time
isRoundNavigation	boolean	Optional, default: false	Enable round carousel navigation (when left or right limits are reached, navigate to each other)
hideNavigationButtons	boolean	Optional, default: false	Force hide left and right navigation buttons (all the time, can be used with isDragDropEnabled)
hideNavigationButtonsWhenNotNeeded	boolean	Optional, default: true	Hide left and right navigation buttons when navigation can not be done due to the little number of elements
isDragDropEnabled	boolean	Optional, default: true	Enable drag-drop navigation (without using the left and right buttons)
stickToClosestElement	boolean	Optional, default: true	Stick navigation view window to closest element edge after drag-drop movement

@Output()

Output	Type	Description
hasMoved	boolean	Emits true when drag movement starts and false 200ms after drag ends; can be watched and used to prevent carousel element clicks or trigger other actions after drag ends

ng-template

Template	Description
contentTemplate	Template for each carousel item
placeholderTemplate	Template for each placeholder item
leftButtonTemplate	Template for left scroll button
rightButtonTemplate	Template for right scroll button