Tailwind CSS Stepper Plugin API

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

Installation

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

Terminal

                        
                          npm i @preline/stepper

Example

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

1 Step
2 Step
3 Step

First content

Basic usage

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

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

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

                      
                        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.

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

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

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 Stepper Plugin API

First content

Second content

Third content

Final content

On this page