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

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

Tailwind CSS Stepper Plugin API

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

JavaScript Typescript

Installation

To get started, install Stepper 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/stepper via npm

    Terminal 
                              
                            npm i @preline/stepper

  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/stepper */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/stepper/*.js";
                            @import "./node_modules/@preline/stepper/variants.css";
                            @import "./node_modules/@preline/stepper/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/stepper";
    JavaScript (non-auto) 
                              
                            import HSStepper from "@preline/stepper/non-auto";
                            
                            HSStepper.autoInit();
                            
                            // Or initialize a specific element manually
                            const el = document.querySelector("#stepper");
                            if (el) new HSStepper(el);

Example

A customizable stepper component for guiding users through multi-step processes.

Basic usage

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

HTML 
                      
                        <div data-hs-stepper>
                          <div class="hs-stepper-active:text-blue-500 hs-stepper-success:text-blue-500" data-hs-stepper-nav-item='{
                            "index": 1
                          }'>
                            1 Step
                          </div>
                          <div class="hs-stepper-active:text-blue-500 hs-stepper-success:text-blue-500" data-hs-stepper-nav-item='{
                            "index": 2
                          }'>
                            2 Step
                          </div>
                          <div class="hs-stepper-active:text-blue-500 hs-stepper-success:text-blue-500" data-hs-stepper-nav-item='{
                            "index": 3
                          }'>
                            3 Step
                          </div>
                          
                          <div data-hs-stepper-content-item='{
                            "index": 1
                          }' style="display: none;">
                            First content.
                          </div>
                          <div data-hs-stepper-content-item='{
                            "index": 2
                          }' style="display: none;">
                            Second content.
                          </div>
                          <div data-hs-stepper-content-item='{
                            "index": 3
                          }' style="display: none;">
                            Third content.
                          </div>
                          <div data-hs-stepper-content-item='{
                            "isFinal": true
                          }' style="display: none;">
                            Final content.
                          </div>
                          
                          <button class="hs-stepper-disabled:opacity-50" type="button" data-hs-stepper-back-btn>
                            Back
                          </button>
                          <button type="button" data-hs-stepper-skip-btn style="display: none;">
                            Skip
                          </button>
                          <button type="button" data-hs-stepper-next-btn>
                            Next
                          </button>
                          <button type="button" data-hs-stepper-finish-btn style="display: none;">
                            Finish
                          </button>
                          <button type="reset" data-hs-stepper-reset-btn style="display: none;">
                            Reset
                          </button>
                        </div>

JavaScript behavior

Data Options

Name Description Options Default value
data-hs-stepper Activate a Stepper by specifying on an element. Should be added to the container. — —
:currentIndex Index of the current step. This must be a number between 1 and the maximum number of steps. number 1
:mode The mode of the stepper. In "non-lenear" mode, the user can navigate to any step and nav items itself are clickable. In "linear" mode, the user can only navigate to the next/back step. "linear" | "non-linear" linear
:isCompleted Whether the stepper is completed. boolean false
data-hs-stepper-nav-item Activate a Stepper Nav Item by specifying on an element. Should be added to the nav item. — —
:index The index of the step to which the item belongs. This must be a number between 1 and the maximum number of steps. number —
:isOptional Whether the step is optional. boolean false
:isCompleted Whether the step is completed. boolean false
:isSkip Whether the step is skipped. boolean false
:hasError Whether the step has an error. boolean false
data-hs-stepper-content-item Activate a Stepper Content Item by specifying on an element. Should be added to the content item. — —
:index The index of the step to which the item belongs. This must be a number between 1 and the maximum number of steps. number —
:isCompleted Whether the step is completed. boolean false
:isSkip Whether the step is skipped. boolean false
:isFinal Whether the step is final. boolean false

Tailwind Modifiers

Name Description
hs-stepper-active:* Modifies the active step.
hs-stepper-success:* Modifies the completed step.
hs-stepper-disabled:* Modifies the "back" button when the very first step is active.
hs-stepper-skipped:* Modifies the skipped step.
hs-stepper-error:* Modifies the step that has error. Error class should be added manually by some event. E.g. after form validation.
hs-stepper-process:* Modifies the step that processing. Process class should be added manually by some event. E.g. after form submit.
hs-stepper-completed:* Modifies all steps are completed.

Methods

The HSStepper object is contained within the global window object

Method Description
Public methods
setProcessedNavItem(n) Set the nav item as processed. Available parameters:
  • n the index of the step to which the item belongs
setErrorNavItem(n) Set the nav item as error. Available parameters:
  • n the index of the step to which the item belongs
unsetProcessedNavItem(n) Unset the nav item as processed. Available parameters:
  • n the index of the step to which the item belongs
goToNext() Go to the next step. The method returns the index of the next step. If the current step is the last, the method returns the index of the current step.
goToFinish() Go to the finish step. The method returns the index of the finish step. If the current step is the last, the method returns the index of the current step.
disableButtons() Disable the "next" and "back" buttons.
enableButtons() Enable the "next" and "back" buttons.
destroy() Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
HSStepper.getInstance(target, isInstance) Returns the element associated to the target.
  • target should be a Node or string (valid selector)
  • isInstance boolean. Returns the instance instead of Node if true

Randomize an error state (public method).

JavaScript 
                      
                        const stepper = new HSStepper(document.querySelector('#stepper'));
                        let errorState = 1;
                        
                        stepper.on('beforeNext', (index) => {
                          if (index === 2) {
                            stepper.setProcessedNavItem(index);
                            
                            setTimeout(() => {
                              stepper.unsetProcessedNavItem(index);
                              stepper.enableButtons();
                              
                              if (errorState) {
                                stepper.goToNext();
                              } else {
                                stepper.setErrorNavItem(index);
                              }
                              
                              errorState = !errorState;
                            }, 2000);
                          }
                        });

Randomize an error state (mixed).

JavaScript 
                      
                        const stepper = HSStepper.getInstance('#stepper');
                        let errorState = 1;
                        
                        stepper.on('beforeNext', (index) => {
                          if (index === 2) {
                            stepper.setProcessedNavItem(index);
                            
                            setTimeout(() => {
                              stepper.unsetProcessedNavItem(index);
                              stepper.enableButtons();
                              
                              if (errorState) {
                                stepper.goToNext();
                              } else {
                                stepper.setErrorNavItem(index);
                              }
                              
                              errorState = !errorState;
                            }, 2000);
                          }
                        });

Events

Method Description Returned value
on:active The event is triggered when the "active" class setup. currentIndex
on:beforeNext The event is triggered before the "next" button is clicked. currentIndex
on:beforeFinish The event is triggered before the "finish" button is clicked. currentIndex
on:next The event is triggered when the "next" button is clicked. currentIndex
on:back The event is triggered when the "back" button is clicked. currentIndex
on:complete The event is triggered when the "complete" button is clicked. currentIndex
on:finish The event is triggered when the "finish" button is clicked. currentIndex
on:skip The event is triggered when the "skip" button is clicked. currentIndex
on:reset The event is triggered when the "reset" button is clicked. currentIndex

An example when a function is run before the next step.

JavaScript 
                      
                        const el = HSStepper.getInstance('#stepper');

                        el.on('next', (currentIndex) => {...});

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.

Stepper

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

View Stepper examples

Stepper

© 2026 Preline Labs.