Carousel

Carousel is a content slider featuring various customization options.

Basic

Circular, AutoPlay, 3 Items per Page and Scroll by 1

Vertical

Import via Module


import { Carousel } from 'primereact/carousel';

Import via CDN


<script src="https://unpkg.com/primereact/core/core.min.js"></script>
<script src="https://unpkg.com/primereact/carousel/carousel.min.js"></script>

Getting Started

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


<Carousel value={products} itemTemplate={itemTemplate}></Carousel>


const itemTemplate = (product) => {
    // return content;
}

Items per page and Scroll Items

Number of items per page is defined using the numVisible property whereas number of items to scroll is defined with the numScroll property.


<Carousel value={products} itemTemplate={itemTemplate} numVisible={3} numScroll={1}></Carousel>

Responsive

For responsive design, numVisible and numScroll can be defined using the responsiveOptions property that should be an array of objects whose breakpoint defines the max-width to apply the settings.


<Carousel value={products} itemTemplate={itemTemplate} numVisible={3} numScroll={1} responsiveOptions={responsiveOptions}></Carousel>


const responsiveOptions = [
    {
        breakpoint: '1024px',
        numVisible: 3,
        numScroll: 3
    },
    {
        breakpoint: '768px',
        numVisible: 2,
        numScroll: 2
    },
    {
        breakpoint: '560px',
        numVisible: 1,
        numScroll: 1
    }
];

Header and Footer

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


<Carousel value={products} itemTemplate={itemTemplate} header={<h1>Header</h1>}></Carousel>

Orientation

Default layout of the Carousel is horizontal, other possible option is the vertical mode that is configured with the orientation property.


<Carousel value={products} itemTemplate={itemTemplate} orientation="vertical"></Carousel>

AutoPlay and Circular

When autoplayInterval is defined in milliseconds, items are scrolled automatically. In addition, for infinite scrolling circular property needs to be enabled. Note that in autoplay mode, circular is enabled by default.

Controlled vs Uncontrolled

In controlled mode, page and onPageChange properties need to be defined to control the first visible item.


<Carousel value={products} itemTemplate={itemTemplate} page={page} onPageChange={(e) => setPage(e.page)}></Carousel>

Uncontrolled

In uncontrolled mode, no additional properties are required. Initial page can be provided using the page property in uncontrolled mode however it is evaluated at initial rendering and ignored in further updates. If you programmatically need to update the first visible item index, prefer to use the component as controlled.


<Carousel value={products} itemTemplate={itemTemplate}></Carousel>

Properties

Name	Type	Default	Description
id	string	null	Unique identifier of the element.
value	array	null	An array of objects to display.
page	number	null	Index of the first item.
header	any	null	Label of header.
footer	any	null	Label of footer.
style	string	null	Inline style of the component.
className	string	null	Style class of the component.
itemTemplate	function	null	Function that gets an item in the value and returns the content for it.
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.
circular	boolean	false	Defines if scrolling would be infinite.
autoplayInterval	number	null	Time in milliseconds to scroll items automatically.
numVisible	number	1	Number of items per page.
numScroll	number	1	Number of items to scroll.
responsiveOptions	any	null	An array of options for responsive design.
orientation	string	horizontal	Specifies the layout of the component, valid values are "horizontal" and "vertical".
verticalViewPortHeight	string	300px	Height of the viewport in vertical layout.
contentClassName	string	null	Style class of main content.
containerClassName	string	null	Style class of the viewport container.
indicatorsContentClassName	string	null	Style class of the paginator items.

Events

Name	Parameters	Description
onPageChange	event.page = Value of the new page.	Callback to invoke after scroll.

Styling

Following is the list of structural style classes

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-indicators	Container of the indicators.
p-carousel-indicator	Indicator element.