Update v4.2 - New components, 10+ framework guides, and quality improvements. Visit Changelog

........ Github
Figma X (Twitter)

Tailwind CSS Carousel Plugin API

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

JavaScript Typescript

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.

  1. Install the plugin

    Install @preline/carousel via npm

    Terminal 
                              
                            npm i @preline/carousel

  2. Add the plugin CSS

    Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

    main.css 
                              
                            @import "tailwindcss";
                            
                            /* @preline/carousel */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/carousel/*.js";
                            @import "./node_modules/@preline/carousel/variants.css";
                            @import "./node_modules/@preline/carousel/theme.css";

  3. Add the plugin JavaScript

    Include the JavaScript <script> that powers the interactive elements near the end of your </body> tag:

    HTML

    Additional Initialization Options

    Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

    HTML (non-auto)

    Via bundler

    When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

    JavaScript (auto) 
                              
                            import "@preline/carousel";
    JavaScript (non-auto) 
                              
                            import HSCarousel from "@preline/carousel/non-auto";
                            
                            HSCarousel.autoInit();
                            
                            // Or initialize a specific element manually
                            const el = document.querySelector("#carousel");
                            if (el) new HSCarousel(el);

Example

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

Basic usage

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

HTML 
                      
                        <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 inset-s-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).

JavaScript 
                      
                        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).

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

Ready to use Components

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

Carousel

Explore ready-to-use Tailwind CSS examples built with Preline UI.

View Carousel examples

Carousel

© 2026 Preline Labs.