ruclib-carousel

This library provides a flexible and customizable carousel component for your Angular applications. Users can integrate the carousel component using Angular services or selectors with ease. Below are the features, usage instructions, and integration details

Installation Guide

To use the Carousel component, you can install the entire RUC library or just this specific component.

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Carousel component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

📦 Version Compatibility

| Angular Version | Compatible Version | Installation Command | |-----------------|--------------------|----------------------------------------------------------------------------------------| | 15.x.x | 3.2.0 | npm install @ruc-lib/carousel@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0 | | 16.x.x | 3.2.0 | npm install @ruc-lib/carousel@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0 | | 17.x.x | 4.0.0 | npm install @ruc-lib/carousel@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0 | | 18.x.x | 4.0.0 | npm install @ruc-lib/carousel@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0 | | 19.x.x | 4.0.0 | npm install @ruc-lib/carousel@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0 | | 20.x.x | 4.0.0 | npm install @ruc-lib/carousel@^4.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibCarouselComponent:

import { Component } from '@angular/core';

// For Complete Library
import { RuclibCarouselComponent } from '@uxpractice/ruc-lib/carousel';

// For Individual Package
import { RuclibCarouselComponent } from '@ruc-lib/carousel';

@Component({
  selector: 'app-root',
  imports: [RuclibCarouselComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}

2. Use the Component

In your component's template, use the <uxp-ruclib-carousel> selector and pass the configuration object to the rucInputData input.

<uxp-ruclib-carousel [customTheme]="customTheme" [rucInputData]="inputObjectDataCarousel"></uxp-ruclib-carousel>

API Reference

Component Inputs

| Input | Type | Description | |----------------|--------------------|----------------------------------------------| | rucInputData | CarouselConfig | The main configuration object for the component. | | customTheme | string | An optional CSS class for custom theming. |

CarouselConfig

This is the main configuration object for the Carousel.

| Property | Type | Description | |-----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------| | items | CarouselItem[] | Items to display in the carousel | | direction | 'horizontal' \| 'vertical' | Direction of the carousel scroll | | autoScroll | boolean | Auto Scroll of the Carousel | | autoScrollInterval | number | Interval for Auto Scroll | | prevIcon | string' | Previous Icon | | nextIcon | string' | Next Icon | | templateStyle | 'rectangle' \| 'circle' | Template of the Carousel | | fontSizes | string | User can provide font sizes of header, body and footer | | imageDimensions | string | User can provide image dimesnions- width, height and radius |

CarouselItem

This object defines the configuration for each carousel item within the Carousel Component.

| Property | Type | Description | |-----------|------------------------------------|--------------------------------------------------------------------------| | image | string | The image to be displayed on the carousel | | header | string | Header title of the Carousel Item | | body | string | The content body of the Carousel Item | | footer | string | The footer content |

Example Configuration

Here's an example of how to configure the Carousel in your component's TypeScript file.

import { Component } from '@angular/core';

// For Complete Library
import { CarouselConfig } from '@uxpractice/ruc-lib/carousel';

// For Individual Package
import { CarouselConfig } from '@ruc-lib/carousel';


@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  caraouselConfig: CarouselConfig = {
  items: [
  {
    image: 'https://images.unsplash.com/photo-1746184564778-87d9a18ca114?q=80&w=1472&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'First Slide',
    body: 'This is the first slide body',
    footer: 'Footer 1'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Second Slide',
    body: 'This is the second slide body', 
    footer: 'Footer 2'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Third Slide',
    body: 'This is the third slide body',
    footer: 'Footer 3'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Fourth Slide',
    body: 'This is the fourth slide body',
    footer: 'Footer 4'
  }
],
    direction: 'vertical',
    autoScroll: false,
    autoScrollInterval: 2000,
    prevIcon: 'keyboard_arrow_up',
    nextIcon: 'keyboard_arrow_down',
    templateStyle: 'rectangle',
  };
}

⚠️ IMPORTANT: Custom Theme Usage in Angular Material

When implementing custom themes, such as:

.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Carousel Component Library. If you have any feedback or suggestions, please let us know!