Tailwind CSS Carousel

A slideshow component for cycling through elements-images or slides of text-like a carousel.

Installation

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

                      
                        npm i @preline/carousel

Example

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

                          
                            <div data-hs-carousel='{
                                "loadingClasses": "opacity-0"
                              }' class="relative">
                              <div class="hs-carousel relative overflow-hidden w-full min-h-[350px] bg-white rounded-lg">
                                <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">
                                    <div class="flex justify-center h-full bg-gray-100 p-6">
                                      <span class="self-center text-4xl transition duration-700">First slide</span>
                                    </div>
                                  </div>
                                  <div class="hs-carousel-slide">
                                    <div class="flex justify-center h-full bg-gray-200 p-6">
                                      <span class="self-center text-4xl transition duration-700">Second slide</span>
                                    </div>
                                  </div>
                                  <div class="hs-carousel-slide">
                                    <div class="flex justify-center h-full bg-gray-300 p-6">
                                      <span class="self-center text-4xl transition duration-700">Third slide</span>
                                    </div>
                                  </div>
                                </div>
                              </div>

                              <button type="button" class="hs-carousel-prev hs-carousel:disabled:opacity-50 disabled:pointer-events-none absolute inset-y-0 start-0 inline-flex justify-center items-center w-[46px] h-full text-gray-800 hover:bg-gray-800/[.1]">
                                <span class="text-2xl" aria-hidden="true">
                                  <svg class="flex-shrink-0 w-5 h-5" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m15 18-6-6 6-6"/></svg>
                                </span>
                                <span class="sr-only">Previous</span>
                              </button>
                              <button type="button" class="hs-carousel-next hs-carousel:disabled:opacity-50 disabled:pointer-events-none absolute inset-y-0 end-0 inline-flex justify-center items-center w-[46px] h-full text-gray-800 hover:bg-gray-800/[.1]">
                                <span class="sr-only">Next</span>
                                <span class="text-2xl" aria-hidden="true">
                                  <svg class="flex-shrink-0 w-5 h-5" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
                                </span>
                              </button>

                              <div class="hs-carousel-pagination flex justify-center absolute bottom-3 start-0 end-0 space-x-2">
                                <span class="hs-carousel-active:bg-blue-700 hs-carousel-active:border-blue-700 w-3 h-3 border border-gray-400 rounded-full cursor-pointer"></span>
                                <span class="hs-carousel-active:bg-blue-700 hs-carousel-active:border-blue-700 w-3 h-3 border border-gray-400 rounded-full cursor-pointer"></span>
                                <span class="hs-carousel-active:bg-blue-700 hs-carousel-active:border-blue-700 w-3 h-3 border border-gray-400 rounded-full cursor-pointer"></span>
                              </div>
                            </div>

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-[350px]">
                            <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

Options

Name	Description	Options	Default value
`data-hs-carousel`	Activate a carousel by specifying on an element.	—	—
`: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`
`:isAutoPlay`	Enables autoplay.	boolean	`false`
`:speed`	Autoplay animation speed. Available if `isAutoplay: true`.	number	`4000`
`:isInfiniteLoop`	Enables infinite loop.	boolean	`true`

Classes

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.
`hs-carousel-active:`	A modifier that allows you to set Tailwind classes when the active slide was shown.

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.
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 Carousel

Tailwind CSS Carousel

On this page