ng-smooth-carousel

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

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 ✅

Coming Soon

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

Installation

For Angular 14:

1npm install ng-smooth-carousel@14.1.2

Or with yarn:

1yarn add ng-smooth-carousel@14.1.2

Usage

1. Import the NgSmoothCarouselModule in your module:

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

2. For standalone components:

1import { Component } from '@angular/core';
2import { NgSmoothCarouselModule } from 'ng-smooth-carousel';
3
4@Component({
5  // ...
6  standalone: true,
7  imports: [NgSmoothCarouselModule]
8})
9export class YourComponent {}

3. Use in your template:

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

4. Configure in your component:

1import { Component } from '@angular/core';
2import { CarouselConfig } from 'ng-smooth-carousel';
3
4@Component({
5  // ...
6})
7export class YourComponent {
8  items = [
9    { title: 'Item 1' },
10    { title: 'Item 2' },
11    // ...
12  ];
13
14  carouselConfigs: CarouselConfig = {
15    containerWidth: '100%',
16    containerHeight: '350px',
17    itemWidth: '465px',
18    itemHeight: '100%',
19    itemGap: '24px',
20    scrollSize: '10xl',
21    navigationStyle: {
22      buttonShape: 'circle',
23      nextButton: {
24        backgroundColor: '#fff',
25        color: '#333',
26        boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
27        border: '1px solid #333',
28        zIndex: '9999',
29        position: 'absolute',
30        top: '75%',
31        right: '10px',
32        width: '40px',
33        height: '40px',
34        transform: 'translateY(-50%)'
35      },
36      prevButton: {
37        backgroundColor: '#fff',
38        color: '#333',
39        boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
40        zIndex: '9999',
41        position: 'absolute',
42        top: '75%',
43        left: '10px',
44        width: '40px',
45        height: '40px',
46        transform: 'translateY(-50%)'
47      }
48    }
49  }
50}

Basic Carousel

1carouselConfig: CarouselConfig = {
2  containerWidth: '100%',
3  containerHeight: '300px',
4  itemWidth: '400px',
5  itemHeight: '100%',
6  itemGap: '24px',
7  navigationStyle: {
8    buttonShape: 'rounded',
9  },
10};

Example with Custom Empty State Template

1<nsc [items]="products" [config]="carouselConfig">
2  <!-- Regular item template -->
3  <ng-template #carouselItem let-item>
4    <div class="custom-item">
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">
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</nsc>

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 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
ctaPosition	string	'bottom-right'	Position of navigation controls

Advanced Features

Property	Type	Default	Description
autoplay	boolean	false	Enable autoplay ✅
autoplayDelay	string	'3000ms'	Delay between autoplay slides ✅
loop	boolean	false	Enable infinite loop ❌
enableSearch	boolean	false	Enable search functionality
searchPlaceholder	string	'Search...'	Placeholder text for search input ❌
searchModalTitle	string	'Search Items'	Title for search modal ❌
enableOneItemScroll	boolean	false	Enable scrolling one item at a time ✅

Full-Width Single Item Carousel

To create a carousel that displays and scrolls through one full-width item at a time (common for hero sliders or product showcases), use the following configuration:

1carouselConfig: CarouselConfig = {
2  containerWidth: '100%',
3  containerHeight: '350px',
4  itemWidth: '100%',
5  itemHeight: '100%',
6  enableOneItemScroll: true,
7  navigationStyle: {
8    buttonShape: 'rounded',
9    nextButton: {
10      backgroundColor: '#fff',
11      color: '#333',
12      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
13      top: '75%',
14      right: '-2px',
15      width: '40px',
16      height: '60px',
17      transform: 'translateY(-50%)'
18    },
19    prevButton: {
20      backgroundColor: '#fff',
21      color: '#333',
22      boxShadow: '0 2px 8px rgba(0,0,0,0.25)',
23      top: '75%',
24      left: '-2px',
25      width: '40px',
26      height: '60px',
27      transform: 'translateY(-50%)'
28    }
29  }
30}

This configuration creates a clean, full-width carousel where each item takes up the entire container width and scrolls individually.

Scroll Sizes

The scrollSize property accepts the following values, each moving by a specific number of pixels:

1type ScrollSize = 
2  | 'xs'   // 50px
3  | 'sm'   // 100px
4  | 'md'   // 150px
5  | 'lg'   // 200px
6  | 'xl'   // 250px
7  | '2xl'  // 300px
8  | '3xl'  // 350px
9  | '4xl'  // 400px
10  | '5xl'  // 450px
11  | '6xl'  // 500px
12  | '7xl'  // 550px
13  | '8xl'  // 600px
14  | '9xl'  // 650px
15  | '10xl' // 700px

Button Shapes

The buttonShape property in navigationStyle accepts:

1type NavButtonShape = 'circle' | 'rounded' | 'square';

NavigationStyle Interface

1interface NavigationStyle {
2  nextButton?: Record<string, string> | ButtonStyle;
3  prevButton?: Record<string, string> | ButtonStyle;
4  buttonShape?: NavButtonShape;
5  icons?: {
6    next?: string;
7    prev?: string;
8    search?: string;
9    vertical?: {
10      next?: string;
11      prev?: string;
12    };
13  };
14}

ButtonStyle Interface

1interface ButtonStyle {
2  backgroundColor?: string;
3  color?: string;
4  borderRadius?: string;
5  padding?: string;
6  fontSize?: string;
7  border?: string;
8  boxShadow?: string;
9  top?: string;
10  bottom?: string;
11  left?: string;
12  right?: string;
13  zIndex?: string;
14  transform?: string;
15  position?: string;
16} 

SearchStyle Interface

1interface SearchStyle {
2  button?: Record<string, string>;
3  modal?: Record<string, string>;
4}

Angular Version Compatibility

Angular Version	Package Version
Angular 14	14.1.0
Angular 17+	Coming soon

Demo

Horizontal

Vertical

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.