Carousel

Carousel is a content slider featuring various customization options.

Import #


import { CarouselModule } from 'primeng/carousel';

Basic #

Carousel requires a collection of items as its value along with a template to render each item.


<p-carousel 
    [value]="products" 
    [numVisible]="3" 
    [numScroll]="3" 
    [circular]="false" 
    [responsiveOptions]="responsiveOptions">
        <ng-template let-product pTemplate="item">
            <div class="border-1 surface-border border-round m-2 p-3">
                <div class="mb-3">
                    <div class="relative mx-auto">
                        <img 
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                            [alt]="product.name" 
                            class="w-full border-round" />
                        <p-tag 
                            [value]="product.inventoryStatus" 
                            [severity]="getSeverity(product.inventoryStatus)" 
                            class="absolute" 
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-3 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-content-between align-items-center">
                <div class="mt-0 font-semibold text-xl">
                    {{ '$' + product.price }}
                </div>
                    <span>
                        <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                        <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                    </span>
                </div>
            </div>
        </ng-template>
</p-carousel>

Circular #

When autoplayInterval is defined in milliseconds, items are scrolled automatically. In addition, for infinite scrolling circular property needs to be added which is enabled automatically in auto play mode.


<p-carousel 
    [value]="products" 
    [numVisible]="3" 
    [numScroll]="3" 
    [circular]="true" 
    [responsiveOptions]="responsiveOptions" 
    autoplayInterval="3000">
        <ng-template let-product pTemplate="item">
                <div class="border-1 surface-border border-round m-2 p-3">
                    <div class="mb-3">
                        <div class="relative mx-auto">
                            <img 
                                src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                                [alt]="product.name" 
                                class="w-full border-round" />
                            <p-tag 
                                [value]="product.inventoryStatus" 
                                [severity]="getSeverity(product.inventoryStatus)" 
                                class="absolute" 
                                [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                        </div>
                    </div>
                    <div class="mb-3 font-medium">
                        {{ product.name }}
                    </div>
                    <div class="flex justify-content-between align-items-center">
                    <div class="mt-0 font-semibold text-xl">
                        {{ '$' + product.price }}
                    </div>
                        <span>
                            <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                            <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                        </span>
                    </div>
                </div>
        </ng-template>
</p-carousel>

Num Scroll #

Number of items to scroll is specified with the numScroll option.


<p-carousel 
    [value]="products" 
    [numVisible]="3" 
    [numScroll]="1" 
    [responsiveOptions]="responsiveOptions">
        <ng-template let-product pTemplate="item">
            <div class="border-1 surface-border border-round m-2 p-3">
                <div class="mb-3">
                    <div class="relative mx-auto">
                        <img 
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                            [alt]="product.name" 
                            class="w-full border-round" />
                        <p-tag 
                            [value]="product.inventoryStatus" 
                            [severity]="getSeverity(product.inventoryStatus)" 
                            class="absolute" 
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-3 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-content-between align-items-center">
                    <div class="mt-0 font-semibold text-xl">
                        {{ '$' + product.price }}
                    </div>
                    <span>
                        <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                        <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                    </span>
                </div>
            </div>
        </ng-template>
</p-carousel>

Custom Content #

Custom content projection is available using the header and footer templates.

Header content


<p-carousel 
    [value]="products" 
    [numVisible]="3" 
    [numScroll]="1" 
    [responsiveOptions]="responsiveOptions">
        <ng-template pTemplate="header">
            <p>Header content</p>
        </ng-template>
        <ng-template let-product pTemplate="item">
            <div class="border-1 surface-border border-round m-2 p-3">
                <div class="mb-3">
                    <div class="relative mx-auto">
                        <img 
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                            [alt]="product.name" 
                            class="w-full border-round" />
                        <p-tag 
                            [value]="product.inventoryStatus" 
                            [severity]="getSeverity(product.inventoryStatus)" 
                            class="absolute" 
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-3 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-content-between align-items-center">
                    <div class="mt-0 font-semibold text-xl">
                        {{ '$' + product.price }}
                    </div>
                    <span>
                        <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                        <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                    </span>
                </div>
            </div>
        </ng-template>
        <ng-template pTemplate="footer">
            <p>Footer content</p>
        </ng-template>
</p-carousel>

Responsive #

Carousel supports specific configuration per screen size with the responsiveOptions property that takes an array of objects where each object defines the max-width breakpoint, numVisible for the number of items per page and numScroll for number of items to scroll. When responsiveOptions is defined, the numScroll and numVisible properties of the Carousel are used as default when there is breakpoint that applies.


<p-carousel 
    [value]="products" 
    [numVisible]="3" 
    [numScroll]="1" 
    [responsiveOptions]="responsiveOptions">
        <ng-template let-product pTemplate="item">
            <div class="border-1 surface-border border-round m-2 p-3">
                <div class="mb-3">
                    <div class="relative mx-auto">
                        <img 
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                            [alt]="product.name" 
                            class="w-full border-round" />
                        <p-tag 
                            [value]="product.inventoryStatus" 
                            [severity]="getSeverity(product.inventoryStatus)" 
                            class="absolute" 
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-3 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-content-between align-items-center">
                    <div class="mt-0 font-semibold text-xl">
                        {{ '$' + product.price }}
                    </div>
                    <span>
                        <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                        <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                    </span>
                </div>
            </div>
        </ng-template>
</p-carousel>

Vertical #

To create a vertical Carousel, orientation needs to be set to vertical along with a verticalViewPortHeight.


<p-carousel 
    [value]="products" 
    [numVisible]="1" 
    [numScroll]="1" 
    orientation="vertical" 
    verticalViewPortHeight="360px">
        <ng-template let-product pTemplate="item">
            <div class="border-1 surface-border border-round m-2 p-3">
                <div class="mb-3">
                    <div class="relative mx-auto">
                        <img 
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" 
                            [alt]="product.name" 
                            class="w-full border-round" />
                        <p-tag 
                            [value]="product.inventoryStatus" 
                            [severity]="getSeverity(product.inventoryStatus)" 
                            class="absolute" 
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-3 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-content-between align-items-center">
                    <div class="mt-0 font-semibold text-xl">
                        {{ '$' + product.price }}
                    </div>
                    <span>
                        <p-button icon="pi pi-heart" severity="secondary" [outlined]="true" />
                        <p-button icon="pi pi-shopping-cart" styleClass="ml-2" />
                    </span>
                </div>
            </div>
        </ng-template>
</p-carousel>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-carousel	Container element.
p-carousel-header	Header section.
p-carousel-footer	Footer section.
p-carousel-content	Main content element. It contains the container of the viewport.
p-carousel-container	Container of the viewport. It contains navigation buttons and viewport.
p-carousel-items-content	Viewport.
p-carousel-dots-container	Container of the paginator.
p-carousel-dot-item	Paginator element.
p-carousel-dot-icon	Paginator element icon.

Accessibility #

Screen Reader

Carousel uses region role and since any attribute is passed to the main container element, attributes such as aria-label and aria-roledescription can be used as well. The slides container has aria-live attribute set as "polite" if carousel is not in autoplay mode, otherwise "off" would be the value in autoplay.

A slide has a group role with an aria-label that refers to the aria.slideNumber property of the locale API. Similarly aria.slide is used as the aria-roledescription of the item. Inactive slides are hidden from the readers with aria-hidden.

Next and Previous navigators are button elements with aria-label attributes referring to the aria.nextPageLabel and aria.firstPageLabel properties of the locale API by default respectively, you may still use your own aria roles and attributes as any valid attribute is passed to the button elements implicitly by using nextButtonProps and prevButtonProps.

Quick navigation elements are button elements with an aria-label attribute referring to the aria.pageLabel of the locale API. Current page is marked with aria-current.

Next/Prev Keyboard Support

Key	Function
tab	Moves focus through interactive elements in the carousel.
enter	Activates navigation.
space	Activates navigation.

Quick Navigation Keyboard Support

Key	Function
tab	Moves focus through the active slide link.
enter	Activates the focused slide link.
space	Activates the focused slide link.
right arrow	Moves focus to the next slide link.
left arrow	Moves focus to the previous slide link.
home	Moves focus to the first slide link.
end	Moves focus to the last slide link.

Carousel API

API defines helper props, events and others for the PrimeNG Carousel module.

Carousel #

Carousel is a content slider featuring various customization options.

Properties #

Defines the input properties of the component.

name	type	default	description
page	number	null	Index of the first item.
numVisible	number	null	Number of items per page.
numScroll	number	null	Number of items to scroll.
responsiveOptions	CarouselResponsiveOptions[]	null	An array of options for responsive design.
orientation	"vertical" \| "horizontal"	horizontal	Specifies the layout of the component.
verticalViewPortHeight	string	300px	Height of the viewport in vertical layout.
contentClass	string	null	Style class of main content.
indicatorsContentClass	string	null	Style class of the indicator items.
indicatorsContentStyle	Object	null	Inline style of the indicator items.
indicatorStyleClass	string	null	Style class of the indicators.
indicatorStyle	Object	null	Style of the indicators.
value	any[]	null	An array of objects to display.
circular	boolean	false	Defines if scrolling would be infinite.
showIndicators	boolean	true	Whether to display indicator container.
showNavigators	boolean	true	Whether to display navigation buttons in container.
autoplayInterval	number	0	Time in milliseconds to scroll items automatically.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the viewport container.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onPage	event : CarouselPageEvent	Callback to invoke after scroll.

Templates #

Defines the templates used by the component.

name	parameters	description
header		Custom template of header.
item	context : { $implicit: any, // Data of the item. }	Custom template of item.
previousicon		Custom template of previousicon.
nexticon		Custom template of nexticon.
footer		Custom template of footer.

Events #

Defines the custom events used by the component's emitters.

CarouselPageEvent #

Custom page event.

name	type	description
page	number	Current page.

Interfaces #

Defines the custom interfaces used by the module.

CarouselResponsiveOptions #

Responsive options of the component.

name	type	description
breakpoint	string	Breakpoint for responsive mode. Exp;
numVisible	number	The number of visible items on breakpoint.
numScroll	number	The number of scrolled items on breakpoint.