Tailwind CSS Carousel Plugin API

Headless, unstyled Carousel plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

Installation

To get started, install Carousel plugin via npm, or skip this step if you are already using Preline UI as a package.

Terminal

                        
                          npm i @preline/carousel

Example

Here is a basic example of a carousel with three slides.

First slide

Second slide

Third slide

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

                      
                        <div data-hs-carousel='{
                            "loadingClasses": "opacity-0"
                          }' class="relative">
                          <div class="hs-carousel relative overflow-hidden w-full min-h-64">
                            <div class="hs-carousel-body absolute top-0 bottom-0 start-0 flex flex-nowrap transition-transform duration-700 opacity-0">
                              <div class="hs-carousel-slide">
                                1
                              </div>
                              <div class="hs-carousel-slide">
                                2
                              </div>
                              <div class="hs-carousel-slide">
                                3
                              </div>
                            </div>
                          </div>

                          <button type="button" class="hs-carousel-prev">
                            <span aria-hidden="true">«</span>
                            <span class="sr-only">Previous</span>
                          </button>
                          <button type="button" class="hs-carousel-next">
                            <span class="sr-only">Next</span>
                            <span aria-hidden="true">»</span>
                          </button>
                        </div>

JavaScript behavior

Data Options

Name	Description	Options	Default value
`data-hs-carousel`	Activate a carousel by specifying on an element. Should be added to the container.	—	—
`:currentIndex`	Specifies the index of the current slide initially (from 0 to slides quantity).	number	`0`
`:loadingClasses`	Specifies which classes should be removed after the carousel is loaded. CSS classes should be separated with space.	string	`opacity-0`
`:dotsItemClasses`	Specifies which classes will be added to the point elements (which are generated automatically). CSS classes should be separated with space.	string	`—`
`:isAutoHeight`	Sets the height of the carousel to the height of the current slide.	boolean	`false`
`:isAutoPlay`	Enables autoplay.	boolean	`false`
`:speed`	Autoplay animation speed. Available if `isAutoplay: true`.	number	`4000`
`:updateDelay`	Allows you to delay the update function when resizing a window. Suitable to a slider with images, for more accurate calculation of the size of the images.	number	`0`
`:isInfiniteLoop`	Enables infinite loop.	boolean	`true`
`:isCentered`	Enables centered mode. This mode adds space on the sides to center the slides.	boolean	`false`
`:isSnap`	Enables a mode in which you can scroll the contents of the slider using the scroll along the x-axis, while the active slider is centered relative to the slider.	boolean	`false`
`:isDraggable`	Adds the ability to change slides using dragging. It requires to add `hs-carousel:dragging:transition-none` class to the `hs-carousel-body`. It's not working with `isSnap: true` option.	boolean	`false`
`:isRTL`	Turns on RTL mode.	boolean	`false`
`:hasSnapSpacers`	Adds additional elements to create a constant centering effect.	boolean	`true`
`:slidesQty`	Allows to set the number of slides to display at a certain screen resolution if the parameter is passed as an object. If the parameter is passed as a number, the specified number of slides will be displayed for all screen resolutions.	object {'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number: number} \| number	`1`

Selectors

Name	Description
`hs-carousel`	A wrapper for a collection of slides. It must contain the `overflow-hidden` class, it is needed for the slider to work correctly.
`hs-carousel-body`	Slides container.
`hs-carousel-slide`	Single slide.
`hs-carousel-prev`	Previous slide button.
`hs-carousel-next`	Next slide button.
`hs-carousel-pagination`	Pagination. If it doesn't contain nested elements, then the dots are generated automatically, and the classes from the `dotsItemClasses` attribute are applied to them. If there are elements with the `hs-carousel-pagination-item` class inside, then they will act as dots, switching will be carried out according to their order (index) in the container.

Tailwind Modifiers

Name	Description
`hs-carousel-active:*`	A modifier that allows you to set Tailwind classes when the active slide was shown.
`hs-carousel-disabled:*`	A modifier that allows you to set Tailwind classes for arrow buttons when the they are `disabled`.
`hs-carousel:dragging:*`	A modifier that allows you to set Tailwind classes for `hs-carousel-body` when dragging.

Methods

The HSCarousel object is contained within the global window object

Method	Description
Public methods
`goToPrev()`	Go to the previous slide.
`goToNext()`	Go to the next slide.
`goTo(index)`	Go to the slide by index. Starts from 0.
`recalculateWidth()`	Recalculate the width of the carousel.
`destroy()`	Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
`HSCarousel.getInstance(target)`	Returns the element associated to the `target`. `target` should be a Node or string (valid selector)

Go to some slide by button click example (public method).

                      
                        const carousel = new HSCarousel(document.querySelector('#carousel'));
                        const goTo2Btn = document.querySelector('#go-to-2-btn');

                        goTo2Btn.addEventListener('click', () => {
                          carousel.goTo(1);
                        });

Go to some slide by button click example (mixed).

                      
                        const carousel = HSCarousel.getInstance('#carousel');
                        const goTo2Btn = document.querySelector('#go-to-2-btn');
                        
                        goTo2Btn.addEventListener('click', () => {
                          carousel.goTo(1);
                        });

Demo examples

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

Check out Preline UI Components

Tailwind CSS Carousel Plugin API

On this page