@ngfly/carousel

A smooth, customizable carousel component for Angular, supporting both vertical and horizontal orientations.

Note: All configurations and examples can be customized to fit your specific needs. Feel free to modify any aspect of the carousel to match your application's requirements.

Demo Coming Soon: Interactive examples and live demos will be available soon!

Features

• 🎯 Smooth scrolling animation ✅
• 🔄 Flexible orientation support (vertical & horizontal) ✅
• 🎨 Highly customizable navigation buttons and styling ✅
• 📱 Responsive design ✅
• 🎮 Multiple navigation options ✅
• 🎯 Custom item templates ✅
• 🔄 Auto-play support ✅
• 🔄 Full-width single item support ✅
• 🎨 Custom empty state templates ✅
• 🎯 Customizable navigation button positions ✅
• 🌟 Standalone component (Angular 17+) ✅
• 🔄 Loop functionality ✅
• 🎯 Customizable indicators with animations ✅
• 🌟 Lazy loading images for performance ✅

Coming Soon

• 🔍 Enhanced search filtering with advanced options ❌
• ⚡ Click-hold-swap interaction for improved user experience ❌

Installation

1npm install @ngfly/carousel

Or with yarn:

1yarn add @ngfly/carousel

Usage

For Standalone Components

Import and use the component directly in your standalone component:

1import { Component } from '@angular/core';
2import { CarouselComponent, CarouselConfig, LazyLoadDirective } from '@ngfly/carousel';
3
4@Component({
5  // ...
6  standalone: true,
7  imports: [CarouselComponent, LazyLoadDirective]
8})
9export class YourComponent {
10  // Your component code
11}

For NgModule-based Applications

1. Import the CarouselModule in your module:

1import { NgModule } from '@angular/core';
2import { CarouselModule } from '@ngfly/carousel';
3
4@NgModule({
5  imports: [
6    CarouselModule
7  ],
8  // ...
9})
10export class YourModule {}

Use in your template:

1<!-- Horizontal Carousel (Default) -->
2<carousel [slides]="slides" [configs]="carouselConfigs">
3  <ng-template #carouselItem let-item>
4    <div class="custom-item w-full h-full">
5      {{ item.title }}
6    </div>
7  </ng-template>
8</carousel>
9
10<!-- Vertical Carousel -->
11<carousel [slides]="slides" [configs]="{ orientation: 'vertical' }">
12  <ng-template #carouselItem let-item>
13    <div class="custom-item w-full h-full">
14      {{ item.title }}
15    </div>
16  </ng-template>
17</carousel>

Sample Slide Data Structure

1slides = [
2  {
3    image: 'https://picsum.photos/200/300',
4    title: 'Slide 1',
5    description: 'This is the first slide'
6  },
7  {
8    image: 'https://picsum.photos/200/300',
9    title: 'Slide 2',
10    description: 'This is the second slide'
11  },
12  {
13    image: 'https://picsum.photos/200/300',
14    title: 'Slide 3',
15    description: 'This is the third slide'
16  }
17];

Using the LazyLoadDirective

The package includes a directive for lazy loading images, which can improve performance, also set height and width explicitly for proper display:

1<carousel [slides]="slides" [configs]="carouselConfigs">
2  <ng-template #carouselItem let-item>
3    <div class="custom-item w-full h-full">
4      <img [carouselLazyLoad]="item.imageUrl" [errorImage]="'assets/images/fallback.png'" [alt]="item.title" class="w-[300px] h-[500px] object-cover">
5    </div>
6  </ng-template>
7</carousel>

Example with Custom Empty State Template

1<carousel [slides]="products" [configs]="carouselConfigs">
2  <!-- Regular item template -->
3  <ng-template #carouselItem let-item>
4    <div class="custom-item w-full h-full">
5      <h3>{{ item.title }}</h3>
6      <p>{{ item.description }}</p>
7      <button>View Details</button>
8    </div>
9  </ng-template>
10
11  <!-- Custom empty state template -->
12  <ng-template #emptyState>
13    <div class="custom-empty-state w-full h-full">
14      <h3>No Products Available</h3>
15      <p>Please check back later or try a different search.</p>
16      <button>Browse All Categories</button>
17    </div>
18  </ng-template>
19</carousel>

The carousel component will use your custom empty state template when there are no items to display, such as when filtering returns no results or when the provided items array is empty.

Configuration Examples

Horizontal Full-Width Carousel with Indicators

Perfect for hero banners or promotional sliders with pagination dots.

1carouselConfig: CarouselConfig = {
2  containerWidth: '100%',
3  containerHeight: '300px',
4  itemWidth: '100%',
5  itemHeight: '100%',
6  singleItemMode: true,
7  showIndicators: true,
8  showNavigation: false,
9  indicatorStyle: {
10    spacing: '4px',
11    position: {
12      bottom: '10px',
13      left: '50%'
14    },
15    active: {
16      backgroundColor: '#007bff',
17      boxShadow: '0 0 5px rgba(0, 123, 255, 0.5)',
18      width: '16px',
19      height: '8px',
20      borderRadius: '4px',
21    },
22    inactive: {
23      backgroundColor: '#e0e0e0',
24      opacity: '0.7',
25      width: '8px',
26      height: '8px',
27    }
28  },
29  navigationStyle: {
30    nextButton: {
31      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
32      width: '40px',
33      height: '40px',
34    },
35    prevButton: {
36      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
37      width: '40px',
38      height: '40px',
39    }
40  }
41};

Horizontal Multi-Item Carousel with Navigation

Great for product showcases or card galleries that display multiple items at once.

1carouselConfig: CarouselConfig = {
2  containerWidth: '700px',
3  containerHeight: '300px',
4  itemWidth: '300px',
5  itemHeight: '100%',
6  itemGap: '24px',
7  scrollSize: 'xl',
8  navigationStyle: {
9    nextButton: {
10      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
11      width: '40px',
12      height: '40px',
13    },
14    prevButton: {
15      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
16      width: '40px',
17      height: '40px',
18    }
19  }
20};

Vertical Multi-Item Carousel with Navigation

Useful for content feeds, sidebar lists, or vertical galleries.

1carouselConfig: CarouselConfig = {
2  containerWidth: '300px',
3  containerHeight: '500px',
4  itemWidth: '100%',
5  itemHeight: '200px',
6  itemGap: '24px',
7  scrollSize: 'xl',
8  orientation: 'vertical',
9  navigationStyle: {
10    nextButton: {
11      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
12      width: '40px',
13      height: '40px',
14    },
15    prevButton: {
16      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
17      width: '40px',
18      height: '40px',
19    }
20  }
21}

Vertical Single-Item Carousel with Navigation

Ideal for story-like content presentation or vertical testimonial sliders.

1carouselConfig: CarouselConfig = {
2  containerWidth: '300px',
3  containerHeight: '500px',
4  itemWidth: '100%',
5  itemHeight: '100%',
6  scrollSize: 'xl',
7  orientation: 'vertical',
8  singleItemMode: true,
9  navigationStyle: {
10    nextButton: {
11      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
12      width: '40px',
13      height: '40px',
14    },
15    prevButton: {
16      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
17      width: '40px',
18      height: '40px',
19    }
20  }
21}

Vertical Single-Item Carousel with Indicators

For vertical storytelling interfaces with discrete pagination display.

1carouselConfig: CarouselConfig = {
2  containerWidth: '300px',
3  containerHeight: '500px',
4  itemWidth: '100%',
5  itemHeight: '100%',
6  scrollSize: 'xl',
7  orientation: 'vertical',
8  singleItemMode: true,
9  showNavigation: false,
10  showIndicators: true,
11  indicatorStyle: {
12    spacing: '4px',
13    animation: {
14      type: 'custom',
15      custom: 'carousel__indicator-expand 0.3s forwards',
16      timing: 'ease-in-out'
17    },
18    position: {
19      bottom: '10px',
20      left: '50%'
21    },
22    active: {
23      backgroundColor: '#007bff',
24      boxShadow: '0 0 5px rgba(0, 123, 255, 0.5)',
25      width: '16px',
26      height: '8px',
27      borderRadius: '4px',
28    },
29    inactive: {
30      backgroundColor: '#e0e0e0',
31      opacity: '0.7',
32      width: '8px',
33      height: '8px',
34    }
35  }
36}

Configuration Options

Basic Configuration

Property	Type	Default	Description
containerWidth	string	'100%'	Width of the carousel container
containerHeight	string	'auto'	Height of the carousel container
itemWidth	string	'200px'	Width of each carousel item
itemHeight	string	'100%'	Height of each carousel item
itemGap	string	'0px'	Gap between carousel items
showNavigation	boolean	true	Show/hide navigation buttons
orientation	'horizontal' | 'vertical'	'horizontal'	Carousel orientation
animationDuration	string	'300ms'	Duration of scroll animation
animationTiming	string	'ease'	Timing function for animation
contentPadding	string	'10px'	Padding for the content area
navigationSize	string	'60px'	Size of navigation areas
navigationPadding	string	'10px'	Padding for navigation areas

Navigation Configuration

Property	Type	Default	Description
navigationStyle.buttonShape	'circle' | 'square' | 'rounded'	'circle'	Shape of navigation buttons
navigationStyle.prevButton	ButtonStyle	{}	Style for previous button
navigationStyle.nextButton	ButtonStyle	{}	Style for next button
navigationStyle.icons	object	{}	Custom icons for navigation buttons

Indicator Configuration

Property	Type	Default	Description
showIndicators	boolean	false	Show/hide pagination indicators
indicatorStyle.active	object	{}	Styles for active indicator
indicatorStyle.inactive	object	{}	Styles for inactive indicators
indicatorStyle.container	object	{}	Styles for indicator container
indicatorStyle.spacing	string	'5px'	Gap between indicators
indicatorStyle.position	object	{}	Position of indicator container
indicatorStyle.animation	object	{}	Animation settings for indicators

Advanced Features

Property	Type	Default	Description
autoplay	boolean	false	Enable autoplay
autoplayDelay	string	'3000ms'	Delay between autoplay slides
loop	boolean	false	Enable infinite loop
scrollSize	string | ScrollSize	'sm'	Size of scroll amount
singleItemMode	boolean	false	Enable one-item-at-a-time scrolling

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please create an issue in the GitHub repository.

Changelog

See CHANGELOG.md for a list of changes and updates.