1. Plugins
  3. Stepper

Plugins

Tailwind CSS Stepper

Dynamic stepper plugin that guides users through the steps of a task.

Image Description

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.

                      
                        npm i @preline/stepper

Example

Example.

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>

Options

Name Description Options Default value
data-hs-stepper Activate a Stepper by specifying on an element. — —
: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. — —
: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. — —
: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

Classes

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.
disableButtons() Disable the "next" and "back" buttons.
enableButtons() Enable the "next" and "back" buttons.
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: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.

Image Description
Check out Preline UI Stepper