NgxFullCarousel - Angular Carousel

ngx-full-carousel is an standalone, reusable, responsive and customizable component for Angular 18, 19 and 20.

It is designed to work with signals and Angular zoneless, providing a lightweight, flexible, and accessible image slider.

Installation

If you want to install the latest version (currently 20):

npm install ngx-full-carousel

Angular 19:

npm install ngx-full-carousel@angular19

Angular 18:

npm install ngx-full-carousel@angular18

Basic Usage

The only required input for ngx-full-carousel is [slides]. All other inputs are optional and can be used to customize the carousel´s behavior and appearance.

slides must be an array of objects with the type CarouselItem[]. You can import this type directly from the library:

import { CarouselItem } from 'ngx-full-carousel';

MiniSliderItem Interface

Here is the exact declaration of the CarouselItem type:

export interface CarouselItem {
  image_url?: string;
  backgroundColor?: string;
  title?: string;
  subtitle?: string;
};

Basic Usage example

import { NgxFullCarousel, CarouselItem } from 'ngx-full-carousel';

@Component({
  imports: [NgxFullCarousel],
  template: `
    <ngx-full-carousel
      [slides]="items()"
    />
  `
})
class App {
  items = signal<CarouselItem[]>([
   { image_url: 'img1.jpg', title: 'First Slide', subtitle: '1st slide subtitle' },
   { image_url: 'img2.jpg', title: 'Second Slide', subtitle: '2nd slide subtitle' },
   ]);
}

Advanced Usage

Optional Attributes

In addition to the "slides" attribute, there are a number of optional attributes to fully customize the carousel.

<ngx-full-carousel
    [slides]="items()" 
    
    [hasOverlay]="true"
    [transitionTime]="800"
    arrowsPlacement="auto"
    [hasCounter]="true"
    indicators="bars"

    [hasAutoplay]="true"
    [autoplayTime]="4000"
    [autoplayResumeTime]="15000"

    (selected)="selectedItem.set($event)"
    
    lang="en"
    accessibilityOptions="accOps()"
>

Below you will find a description of these optional attributes, determined by functionality.

Style Attributes

If you want to edit styles in more detail, see the styles section below.

Autoplay Attributes

Current/selected slide output

You can use (selected) output to get the current slide on screen. For example, if you want to build your own counter.

Accessibility Attributes

This component includes five default languages. When you choose one using the "lang" attribute, all accessibility settings are configured in that language, so you don't have to do anything else.

*** We recommend that if you don't need any languages ​​other than those we offer by default, you use the "lang" attribute. It's easy and respects Wai-aria standards. ***

If you want to set up your own custom aria attributes, you should use the AccessibilityOptions interface. You can import it directly from the componente:

import { AccessibilityOptions } from 'ngx-full-carousel';

Here is the exact declaration of the AccessibilityOptions type:

export interface AccessibilityOptions {
  hostAriaLabel?: string;
  autoplayPauseLabel?: string;
  autoplayPlayLabel?: string;
  prevBtnAriaLabel?: string;
  nextBtnAriaLabel?: string;
  slidesRegionAriaLabel?: string;
  slidesRegionRoleDescription?: string;
  slideAriaLabel?: (currentSlide: number, total: number) => string;
  slideRoleDescription?: string;
};

Here you can see a description of every field in AccessibilityOptions interface. Every field is type string (except slideAriaLabel) and non-required

IMPORTANT:

• All fields are optional, so you can customize only the ones you want. Fields that have not been entered in "AccessibilityOptions" will retain their values ​​based on the selected "lang" (remember, default lang is "en")

Here you have an example of use:

import { NgxFullCarousel, CarouselItem, AccessibilityOptions } from 'ngx-full-carousel';

@Component({
  imports: [NgxFullCarousel],
  template: `
    <ngx-full-carousel
      [slides]="items()"
      [accessibilityOptions]="accOpts()"
    />
  `
})
class App {
  items = signal<CarouselItem[]>([
   { image_url: 'img1.jpg', title: 'First Slide', subtitle: '1st slide subtitle' },
   { image_url: 'img2.jpg', title: 'Second Slide', subtitle: '2nd slide subtitle' },
   ]);

  accOpts = signal<AccessibilityOptions>({
    hostAriaLabel: 'Main carousel CHANGED',
    autoplayPauseLabel: 'Pause carousel autoplay CHANGED',
    autoplayPlayLabel: 'Resume carousel autoplay CHANGED',
    prevBtnAriaLabel: 'Go to previous slide CHANGED',
    nextBtnAriaLabel: 'Go to next slide CHANGED',
    slidesRegionAriaLabel: 'Wide carousel CHANGED',
    slidesRegionRoleDescription: 'Carousel CHANGED',
    slideAriaLabel: (currentSlide: number, total: number) =>
        `CHANGED - Slide ${currentSlide} of ${total}`,
    slideRoleDescription: 'CHANGED - slide',
  });
}

Adding custom content: slide for

You can add the custom content you want into any slide you decide. For doing that you must use ng-template and the SlideForDirective.

Here you have a simple example to add a button in the first slide:

import { NgxFullCarousel, CarouselItem, SlideForDirective } from 'ngx-full-carousel';

@Component({
  imports: [NgxFullCarousel, SlideForDirective],
  template: `
    <ngx-full-carousel
      [slides]="items()"
    >
      <ng-template [slideFor]="0">
        <button>
            Button in first slide
        </button>
      </ng-template>
    
    </ngx-full-carousel>
  `
})
class App {
  items = signal<CarouselItem[]>([
   { image_url: 'img1.jpg', title: 'First Slide', subtitle: '1st slide subtitle' },
   { image_url: 'img2.jpg', title: 'Second Slide', subtitle: '2nd slide subtitle' },
   ]);

}

As you can see in the example above, to add content to a slide you just need to use ng-template and the [slideFor] directive, which recieves the number of slide you want to add custom content.

Adding custom content: outerContent

You also can add content inside the whole carousel. It will be visible even if you navigate through slides. Example of use: imagine that the slider is opened into a modal window. You can easily add a "close button" this way.

import { NgxFullCarousel, CarouselItem } from 'ngx-full-carousel';

@Component({
  imports: [NgxFullCarousel],
  template: `
    <ngx-full-carousel
      [slides]="items()"
    >
      <ng-template #outerContent>
        <button style="position: absolute; top: 1rem; right: 1.5rem;">
            X
        </button>
      </ng-template>
    
    </ngx-full-carousel>
  `
})
class App {
  items = signal<CarouselItem[]>([
   { image_url: 'img1.jpg', title: 'First Slide', subtitle: '1st slide subtitle' },
   { image_url: 'img2.jpg', title: 'Second Slide', subtitle: '2nd slide subtitle' },
   ]);

}

As you can see in the example above, you just have to add <ng-template #outerContent> and use the template reference #outerContent. IMPORTANT: You must set the content inside <ng-template #outerContent> as position: absolute and place it where you want.

Style variables

You can customize styles by using different variables in CSS.

Examples of use:

ngx-full-carousel{
  --carousel-bg: red;
  --carousel-overlay-opacity: 0.8;
  --carousel-accent-color: red;
}

📌 Report or suggest something

Choose the form that best fits your case:

• 🐞 Report a bug
• ✨ Request an improvement for an existing component
• 🧩 Suggest a new component

👉 Or go to the form selector.

License

MIT