ng-content-carousel

Introduction

ng-content-carousel is a standalone, reusable 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 content carousel. It is also fully compatible with SSR, CSR and prerender.

Installation

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


    npm install ng-content-carousel

Angular 19:


    npm install ng-content-carousel@v19-lts

Angular 18:


    npm install ng-content-carousel@v18-lts

Overview

Using ng-content-carousel is easy:

Provide content for the carousel using de contentCarouselItem directive. Each element with this tag will represent one item.
Configure its style, behavior, and accessibility using inputs..
Style it with customizable CSS variables to match your design needs.

Here’s a basic usage example:


    import { NgContentCarousel, ContentCarouselItemDirective } from 'ng-content-carousel';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgContentCarousel, ContentCarouselItemDirective],
  template: `
    <ng-content-carousel>
      <div contentCarouselItem >
        Here goes the item content you want
      </div>
      <div contentCarouselItem >
        Here goes the item content you want
      </div>
    </ng-content-carousel>
  `,
})

As shown in the example below, you just have the import the ContentCarouselItemDirective on your component and use contentCarouselItem on each container (this container can be any label: < a >, < div >, < section >... ).

IMPORTANT: All elements should have the same width so the carousel mechanism works well.

Inputs and Outputs

Here is a list of all input/ouput:

Style & Behavior Inputs

Input	Description	Default
transition	Enables or disables slide transition animation.	true
advanceMode	Defines how the carousel advances (single or page).	'page'
arrowStyle	Sets the arrow appearance (minimal or solid).	'minimal'
hideArrowsOnEdges	Hides navigation arrows when at the first or last slide.	true
hideArrowsWhenNoOverflow	Hides arrows if all items fit within the carousel width.	true

Accessibility Inputs

Input	Description	Default
lang	Select the language for accessibility	'en'
customAria	Set up your own custom aria attributes (more info below)	null

Styling

You can easily customize the component’s appearance using the CSS variables listed below.


    ng-content-carousel{
  margin: 1rem; //Example of property you can change directly for the whole component
  --carousel-accent-color: green;
  --carousel-arrows-solid-bg: red;
  --carousel-arrows-hover-bg: #a538a5;
  --carousel-arrows-hover-color: #ffffff;
  --carousel-transition-time: 1s;
}

Variable	Description	Default
--carousel-accent-color	Defines the main accent color for icons and focus outlines.	currentColor
--carousel-arrows-solid-bg	Background color for solid-style navigation arrows.	#444444
--carousel-arrows-hover-bg	Background color of arrows when hovered.	#acacac
--carousel-arrows-hover-color	Icon color of arrows when hovered.	var(--carousel-accent-color)
--carousel-transition-time	Duration of the carousel slide transition animation.	.3s

When using the carouselItem directive, a predefined class is added to each element: .carousel-item. This class have some predefined properties:


    :host ::ng-deep .carousel-item:focus-visible{
  outline: 2px solid var(--carousel-accent-color);
  outline-offset: -2px;
  border-radius: 4px;
}

:host ::ng-deep .carousel-item{
  padding: 1rem;
}

You can change this initial properties if you want simply using the class in you component:


    ng-content-carousel .carousel-item{
  background-color: blue;
}

IMPORTANT: the component itselfs calculate his width related to items width. If you want to give space between items, use padding.

IMPORTANT: Ideally you will the label with the carouselItem directive as a item container and, if you want to add several labels into it, it is appropiate to use another container inside. For example:


    <ng-content-carousel [accessibilityOptions]="accOpts()">
  <div carouselItem> // Use this as a item container => predefine position, padding...
    <div class=""> // Use another container for the content itself
      <span>Top content</span>
      <span>Middle content</span>
      <span>Bottom content</span>
    </div>
  </div>
</ng-content-carousel>

Accessibility

There are two ways of setting the aria-label attributes: by lang attribute or by customAria attribute (See Accessibility Inputs at Inputs and Outputs section)

If needed, you can import ContentCarouselLangs and ContentCarouselCustomAria types like this:


    import { ContentCarouselLangs, ContentCarouselCustomAria } from 'ng-content-carousel';

'lang' attribute:

The component includes five predefined languages for accessibility labels that you can set easily with the lang attribute:

Laguages can be: english (en), spanish (es), italian (it), french (fr) or deutch (de)

*** We recommend using the lang attribute if you don't need any other languages than the ones provided by default. It's simple and compliant with WAI-ARIA standards. ***


    <ng-content-carousel lang="es" />

💡 If no value is provided in lang, the default language is English (en).

💡 If your application supports multiple languages, you can bind the lang attribute to a signal and link it with a select, for example.

'customAria' attribute:

In addition to the predefined languages available through the lang attribute, you can fully customize the ARIA labels for your menu button by using the customAria input.

This option gives you full control over the text announced by screen readers when the menu is opened or closed — perfect for custom translations, accessibility improvements, or when you want to use a language that is not included in the predefined set.

Here is the exact declaration of the ContentCarouselCustomAria type:


    export interface ContentCarouselCustomAria {
  globalAriaLabel?: string;
  globalRoleDescription?: string;
  prevBtnAriaLabel?: string;
  nextBtnAriaLabel?: string;
  trackRoleDescription?: string;
  trackAriaLabel?: string;
  rangeMessage?: (first: number, last: number, total: number) => string;
};

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

Property	Description
globalAriaLabel	aria-label for the global container. Useful to indicate that the user has entered a carousel component.
globalRoleDescription	Describes the role of the carousel region (e.g., “carousel” or “image gallery”) to assistive technologies.
prevBtnAriaLabel	Label for the “previous” navigation button. Communicates its purpose to screen readers.
nextBtnAriaLabel	Label for the “next” navigation button. Communicates its purpose to screen readers.
trackRoleDescription	Describes the carousel track region that contains the sliding items (e.g., “list of items”).
trackAriaLabel	Label for the carousel track. Can be used to describe what the list contains (e.g., “featured products”).
rangeMessage	Function that returns a message indicating the current visible item range in relation to the total (e.g., “Showing items 1–3 of 10”). Useful for providing dynamic feedback to screen readers.

Example of usage:


    import { NgContentCarousel, ContentCarouselItemDirective, ContentCarouselCustomAria } from 'ng-content-carousel';

  @Component({
    imports: [NgContentCarousel, ContentCarouselItemDirective],
    template: `
      <ng-content-carousel [customAria]="accOpts()">
        <div contentCarouselItem>
          Here goes the item content you want
        </div>
        <div contentCarouselItem>
          Here goes the item content you want
        </div>
      </ng-content-carousel>
    `
  })
  class App {
    accOpts : ContentCarouselCustomAria = {
      globalAriaLabel: 'EDIT Content carousel',
      globalRoleDescription: 'EDIT Carousel of content',
      prevBtnAriaLabel: 'EDIT Go to previous item',
      nextBtnAriaLabel: 'EDIT Go to next item',
      trackRoleDescription: 'EDIT Carousel track',
      trackAriaLabel: 'EDIT Carousel items',
      rangeMessage: (first, last, total) =>
        'EDIT Showing items ' + first + ' to ' + last + ' of ' + total,
    }
  }

💡 Remember that what is indicated in the customAria attribute replaces the default language set in lang.

💡 If you only set one of the properties, the other will use the label from the current lang.