Carousel

Carousel is a content slider featuring various customization options.

Import #


import { Carousel } 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 #item>
            <div class="border border-surface rounded-border m-2 p-4">
                <div class="mb-4">
                    <div class="relative mx-auto">
                        <img
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}"
                            [alt]="product.name"
                            class="w-full rounded-border" />
                        <p-tag
                            [value]="product.inventoryStatus"
                            [severity]="getSeverity(product.inventoryStatus)"
                            class="absolute"
                            styleClass="dark:!bg-surface-900"
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-4 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-between 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 #item>
                <div class="border border-surface-200 dark:border-surface-700 rounded m-2 p-4">
                    <div class="mb-4">
                        <div class="relative mx-auto">
                            <img
                                src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}"
                                [alt]="product.name"
                                class="w-full rounded-border" />
                            <p-tag
                                [value]="product.inventoryStatus"
                                [severity]="getSeverity(product.inventoryStatus)"
                                class="absolute"
                                styleClass="dark:!bg-surface-900"
                                [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                        </div>
                    </div>
                    <div class="mb-4 font-medium">
                        {{ product.name }}
                    </div>
                    <div class="flex justify-between 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>

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 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 #item>
            <div class="border border-surface-200 dark:border-surface-700 rounded m-2 p-4">
                <div class="mb-4">
                    <div class="relative mx-auto">
                        <img
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}"
                            [alt]="product.name"
                            class="w-full rounded-border" />
                        <p-tag
                            [value]="product.inventoryStatus"
                            [severity]="getSeverity(product.inventoryStatus)"
                            class="absolute"
                            styleClass="dark:!bg-surface-900"
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-4 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-between 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="330px" contentClass="flex items-center">
        <ng-template let-product #item>
            <div class="border border-surface-200 dark:border-surface-700 rounded m-2 p-4">
                <div class="mb-4">
                    <div class="relative mx-auto">
                        <img
                            src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}"
                            [alt]="product.name"
                            class="w-full rounded" />
                        <p-tag
                            [value]="product.inventoryStatus"
                            [severity]="getSeverity(product.inventoryStatus)"
                            class="absolute"
                            styleClass="dark:!bg-surface-900"
                            [ngStyle]="{ 'left.px': 5, 'top.px': 5 }" />
                    </div>
                </div>
                <div class="mb-4 font-medium">
                    {{ product.name }}
                </div>
                <div class="flex justify-between 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>

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.

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.
prevButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the Button component.
nextButtonProps	ButtonProps	null	Used to pass all properties of the ButtonProps to the Button 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.

class	description
p-carousel	Class name of the root element
p-carousel-header	Class name of the header element
p-carousel-content-container	Class name of the content container element
p-carousel-content	Class name of the content element
p-carousel-prev-button	Class name of the previous button element
p-carousel-viewport	Class name of the viewport element
p-carousel-item-list	Class name of the item list element
p-carousel-item-clone	Class name of the item clone element
p-carousel-item	Class name of the item element
p-carousel-next-button	Class name of the next button element
p-carousel-indicator-list	Class name of the indicator list element
p-carousel-indicator	Class name of the indicator element
p-carousel-indicator-button	Class name of the indicator button element
p-carousel-footer	Class name of the footer element

token	variable	description
carousel.transition.duration	--p-carousel-transition-duration	Transition duration of root
carousel.content.gap	--p-carousel-content-gap	Gap of content
carousel.indicator.list.padding	--p-carousel-indicator-list-padding	Padding of indicator list
carousel.indicator.list.gap	--p-carousel-indicator-list-gap	Gap of indicator list
carousel.indicator.width	--p-carousel-indicator-width	Width of indicator
carousel.indicator.height	--p-carousel-indicator-height	Height of indicator
carousel.indicator.border.radius	--p-carousel-indicator-border-radius	Border radius of indicator
carousel.indicator.focus.ring.width	--p-carousel-indicator-focus-ring-width	Focus ring width of indicator
carousel.indicator.focus.ring.style	--p-carousel-indicator-focus-ring-style	Focus ring style of indicator
carousel.indicator.focus.ring.color	--p-carousel-indicator-focus-ring-color	Focus ring color of indicator
carousel.indicator.focus.ring.offset	--p-carousel-indicator-focus-ring-offset	Focus ring offset of indicator
carousel.indicator.focus.ring.shadow	--p-carousel-indicator-focus-ring-shadow	Focus ring shadow of indicator
carousel.indicator.background	--p-carousel-indicator-background	Background of indicator
carousel.indicator.hover.background	--p-carousel-indicator-hover-background	Hover background of indicator
carousel.indicator.active.background	--p-carousel-indicator-active-background	Active background of indicator

Carousel

Import #

Basic #

Circular #

Responsive #

Vertical #

Accessibility #

Screen Reader

Next/Prev Keyboard Support

Quick Navigation Keyboard Support

Carousel API

Carousel #

Properties #

Emitters #

Templates #

Events #

CarouselPageEvent #

Interfaces #

CarouselResponsiveOptions #

Carousel Theming

CSS Classes #

Carousel Design Tokens #

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.