How To Use

Basic Instalation

To use this component, you'll need to download the npm package.

From your command line:

# Install this package
$ npm install @triwebdev/carousel-component

Once you have download the package you can import it in the .ts of your component like this:

import { Component, signal } from '@angular/core';
import { CardComponent } from './card/card.component'; /* Your own component */
import { CarouselComponent } from '@triwebdev/carousel-component';

@Component({
  selector: 'carousel-implementation',
  imports: [CardComponent, CarouselComponent],
  templateUrl: './carousel-implementation.component.html',
  styleUrl: './carousel-implementation.component.css'
})

export class CarouselImplementationComponent {
cards = signal([
    {
      /* Each card has its own properties defined in your card component */
      prop1: '1',
      prop2: 2,
      prop3: 3,
      prop4: 2,
      img: '/img/myImg.jpg',
      imgAlt: 'img description',
    }
    {...}
    ])

}

And in your .html like this:

<carousel [cards]="cards()">
  <ng-template let-cardInfo>
    <custom-card [card]="cardInfo"></custom-card>
  </ng-template>
</carousel>

The <carousel></carousel> component comes from the package installed (@triwebdev/carousel-component). The <custom-card></custom-card> comes from your project, where you can create your own card that suits to your theme.

Please note that the <carousel></carousel> component has an input of cards. These cards should be available in the component where you will implement the carousel.

Component Configuration

Once you have the component installed and working you can do small customizations:

Inputs

The component have some different inputs that you can use for customizate the theme.

The cards input is for listing all the cards components with its information. This input is required for the component to work properly.

The maxShowedCards input allows you to limit manually how many cards you want to show in that instance of the carousel. If that limit cannot be reached, the cards count will be updated automatically according to the cards width and the available width.

<carousel [cards]="cards()" [maxShowedCards]="5">
  <ng-template let-cardInfo>
    <custom-card [card]="cardInfo"></custom-card>
  </ng-template>
</carousel>

In this example, the maximum number of displayed cards will be 5, regardless of the available width. The default maxShowedCards is 6.

The scrollBehavior input allows two values: 'manual-only' and 'auto'. The default value is 'manual-only' When setting this input value to 'auto', the carousel will start an auto scroll that never ends. Once it gets to the last card, it starts again from the beginning.

Provider

You can set a provider for this component for configuring the scroll behavior when the scrollBehavior input is set to 'auto'.

For doing this, you can put the following in the app.config.ts of your Angular app:

import { ApplicationConfig, provideZoneChangeDetection } from "@angular/core";
import { provideRouter } from "@angular/router";

import { routes } from "./app.routes";
import { provideCarousel } from "@triwebdev/carousel-component";

export const appConfig: ApplicationConfig = {
  providers: [provideZoneChangeDetection({ eventCoalescing: true }), provideRouter(routes), provideCarousel({ firstMoveDelayMultiplier: 2, msPerMove: 2000 })],
};

As you can see, by using this provider you can change two properties of the scroll behavior:

• The firstMoveDelayMultiplier is for setting a delay on the first move once the scroll has restarted (back to the beginning). If you don't want any delay in this matter, you can set this variable to 1. The default value is 1.5
• The msPerMove is for setting how many miliseconds you want for each card scroll move. The default value is 2000 (2s).

CSS customization

There are 4 css variables that can be overwritten with another values that could fit better to your specific case scenario:

The --cards-gap variable is for definining the distance in between two cards of the carousel. Its default value is 20px. The --arrows-dimensions variable is for defining how big the "next" and "previous" arrows should be. Its default value is 50px. The --content-padding variable is for setting how much padding you would like to have in this component. Its default value is 20px. The --arrows-color variable is for defining the color of the "next" and "previous" arrows. Its default value is #000.

How to change the default values of the css variables

There are two different approaches for doing this.

1. Directly in the html template by overriding the variables in the inline styles (Recommended):

<carousel [cards]="cards()" style="--cards-gap:40px;">
  <ng-template let-cardInfo>
    <custom-card [card]="cardInfo"></custom-card>
  </ng-template>
</carousel>

2. Changing the styles of the component in the .ts of the implementation component:

  protected carousel = viewChild('carouselElement', { read: ElementRef });

  ngAfterViewInit(): void {
    this.carousel()?.nativeElement.style.setProperty('--cards-gap', '40px');
  }

When using the viewChild, you have to make sure to link the variable to the html template:

<carousel [cards]="cards()" #carouselElement>
  <ng-template let-cardInfo>
    <custom-card [card]="cardInfo"></custom-card>
  </ng-template>
</carousel>

Download

You can download the latest installable version of the component here.

Authors

The authors of the project:

GitHub @DavMunHer  ·  LinkedIn @David Muñoz Herrero  · 

GitHub @OscBarCan  ·  LinkedIn @Oscar Barber Canet  ·