Default Stepper
Basic Tailwind CSS Stepper example featuring labeled steps and navigation buttons to guide users through a multi-step process.
<form action="#" class="w-full" method="post">
<div data-stepper="true">
<div class="card">
<div class="card-header flex justify-between items-center gap-4 py-8">
<div class="active flex gap-2.5 items-center" data-stepper-item="#stepper_1">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
1
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 1
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<div class="flex gap-2.5 items-center" data-stepper-item="#stepper_2">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
2
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 2
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<div class="flex gap-2.5 items-center" data-stepper-item="#stepper_3">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
3
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 3
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<div class="flex gap-2.5 items-center" data-stepper-item="#stepper_4">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
4
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 4
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
</div>
<div class="card-body py-16">
<div class="" id="stepper_1">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 1
</div>
</div>
<div class="hidden" id="stepper_2">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 2
</div>
</div>
<div class="hidden" id="stepper_3">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 3
</div>
</div>
<div class="hidden" id="stepper_4">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 4
</div>
</div>
</div>
<div class="card-footer py-8 flex justify-between">
<div>
<button class="btn btn-light stepper-first:hidden" data-stepper-back="true">
Back
</button>
</div>
<div>
<button class="btn btn-light stepper-last:hidden" data-stepper-next="true">
Next
</button>
<button class="btn btn-primary hidden stepper-last:inline-flex">
Submit
</button>
</div>
</div>
</div>
</div>
</form>
Source Code
The following source file manages the CSS styles of the Tailwind CSS Stepper component.
Upon building the assets using
Webpack Build Tools
,
the below file is compiled and added into the
dist/assets/css/styles.css
bundle,
making it available globally across all pages.
| File | Description |
|---|---|
src/core/plugins/components/stepper.js
|
The Tailwind CSS compatible plugin written in PostCSS for applying CSS styles to the Tailwind CSS Stepper component. |
HTML Markup
The following markup outlines the core structure of the Tailwind CSS Stepper component.
<!--begin:Form-->
<form action="#" class="w-full" method="post">
<!--begin:Stepper-->
<div data-stepper="true">
<div class="card">
<!--begin:Stepper items-->
<div class="flex items-center justify-between gap-4 mb-10">
<!--begin:Stepper item 1-->
<div class="active flex gap-2.5 items-center" data-stepper-item="#stepper_1">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
1
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 1
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<!--end:Stepper item 1-->
<!--begin:Stepper item 2-->
<div class="flex gap-2.5 items-center" data-stepper-item="#stepper_2">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
2
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 2
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<!--end:Stepper item 2-->
</div>
<!--end:Stepper items-->
<!--begin:Stepper contents-->
<div class="mb-10">
<!--begin:Stepper content 1-->
<div class="" id="stepper_1">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 1
</div>
</div>
<!--end:Stepper content 1-->
<!--begin:Stepper content 2-->
<div class="hidden" id="stepper_2">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 2
</div>
</div>
<!--end:Stepper content 2-->
</div>
<!--end:Stepper contents-->
<!--begin:Stepper actions-->
<div class="flex items-center justify-between gap-4">
<div>
<button class="btn btn-light stepper-first:hidden" data-stepper-back="true">
Back
</button>
</div>
<div>
<button class="btn btn-light stepper-last:hidden" data-stepper-next="true">
Next
</button>
<button class="btn btn-primary hidden stepper-last:inline-flex">
Submit
</button>
</div>
</div>
<!--end:Stepper actions-->
</div>
</div>
<!--end:Stepper-->
</form>
<!--end:Form-->
Attributes
The following HTML attributes are utilized by the accordion component to control its JavaScript behavior.
| HTML Attribute | Description |
|---|---|
data-stepper-item="#stepper_content_id"
|
Links a step to its content using the ID selector, controlling content visibility based on the active step. |
data-stepper-number="true"
|
Specifies an element that for dynamically print step number. |
Classes
This table details the custom CSS classes used for styling the Tailwind CSS Stepper component.
| Class | Description |
|---|---|
first
|
Applied to the stepper root element when current step is first. |
last
|
Applied to the stepper root element when current step is last. |
between
|
Applied to the stepper root element when current step is between. |
active
|
Applied to the stepper active item. |
completed
|
Applied to the stepper completed item. |
pending
|
Applied to the stepper pending item. |
Variants
Utilize the following Tailwind CSS Stepper variants to manage the appearance of the stepper and it's child elements.
For more information, refer to the
Tailwind CSS Variant documentation
.
| Class | Description |
|---|---|
stepper-first:
|
A custom Tailwind variant activated when the first stepper item is active, indicating the beginning of the stepper process. |
stepper-between:
|
A custom Tailwind variant activated for stepper items that are between the first and last, indicating mid-process steps. |
stepper-last:
|
A custom Tailwind variant activated when the last stepper item is active, indicating the end of the stepper process. |
stepper-item-active:
|
A custom Tailwind variant for the currently active stepper item, highlighting the current step in the process. |
stepper-item-completed:
|
A custom Tailwind variant for stepper items that have been completed, indicating past steps in the process. |
stepper-item-pending:
|
A custom Tailwind variant for stepper items that are pending, indicating future steps yet to be reached in the process. |
<!--begin:Form-->
<form action="#" class="w-full" method="post">
<!--begin:Stepper-->
<div data-stepper="true">
<div class="card">
<!--begin:Stepper items-->
<div class="flex items-center justify-between gap-4 mb-10">
<!--begin:Stepper item 1-->
<div class="active flex gap-2.5 items-center" data-stepper-item="#stepper_1">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
1
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 1
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<!--end:Stepper item 1-->
<!--begin:Stepper item 2-->
<div class="flex gap-2.5 items-center" data-stepper-item="#stepper_2">
<div class="rounded-full size-10 flex items-center justify-center text-md font-semibold bg-primary-light text-primary stepper-item-active:bg-primary stepper-item-active:text-primary-inverse stepper-item-completed:bg-success stepper-item-completed:text-success-inverse">
<span class="stepper-item-completed:hidden" data-stepper-number="true">
2
</span>
<i class="ki-outline ki-check text-xl hidden stepper-item-completed:inline">
</i>
</div>
<div class="flex flex-col gap-0.5">
<h4 class="text-sm font-medium text-gray-900 stepper-item-completed:text-gray-600">
Step 2
</h4>
<span class="text-2sm text-gray-700 stepper-item-completed:text-gray-400">
Description
</span>
</div>
</div>
<!--end:Stepper item 2-->
</div>
<!--end:Stepper items-->
<!--begin:Stepper contents-->
<div class="mb-10">
<!--begin:Stepper content 1-->
<div class="" id="stepper_1">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 1
</div>
</div>
<!--end:Stepper content 1-->
<!--begin:Stepper content 2-->
<div class="hidden" id="stepper_2">
<div class="flex items-center justify-center text-3xl font-semibold text-gray-900">
Step 2
</div>
</div>
<!--end:Stepper content 2-->
</div>
<!--end:Stepper contents-->
<!--begin:Stepper actions-->
<div class="flex items-center justify-between gap-4">
<div>
<button class="btn btn-light stepper-first:hidden" data-stepper-back="true">
Back
</button>
</div>
<div>
<button class="btn btn-light stepper-last:hidden" data-stepper-next="true">
Next
</button>
<button class="btn btn-primary hidden stepper-last:inline-flex">
Submit
</button>
</div>
</div>
<!--end:Stepper actions-->
</div>
</div>
<!--end:Stepper-->
</form>
<!--end:Form-->
Data Attribute Initialization
Auto-initialize all KTStepper instances on page load by adding the
data-stepper="true"
attribute to your stepper element.
This triggers on the fly initialization by the KTStepper JavaScript component.
<div data-stepper="true" data-stepper-active-step="1" id="my_stepper">
...
</div>
These attributes allow you to set options for the KTStepper component during initialization.
The values you provide as strings are automatically converted to the appropriate
KTStepper Options
.
| HTML Attribute | Type | Default | Description |
|---|---|---|---|
data-stepper
|
boolean
|
true
|
Automatically initializes Tailwind CSS Stepper instances on page load. This can be disabled for manual initialization via JavaScript. |
data-stepper-active-step
|
number
|
1
|
Specifies the active step number when the stepper is first initialized, indicating which step should be active at the start. |
data-stepper-hidden-class
|
string
|
"hidden"
|
Defines a Tailwind CSS class applied to hide the stepper contents when they are not active. |
JavaScript Initialization
To initialize a new stepper component, pass the corresponding DOM element and configuration options to the KTStepper class constructor.
const stepperEl = document.querySelector('#my_stepper');
const options = {
activeStep: 1,
hiddenClass: 'hidden'
};
const stepper = new KTStepper(stepperEl, options);
<div data-stepper="false" id="my_stepper">
...
</div>
To initialize the stepper with JavaScript, use
data-stepper="false"
attribute instead.
This prevents automatic initialization on page load.
Options
This table outlines the configuration options for initialization of Tailwind CSS Stepper instances, using the KTStepper JavaScript component.
| Option | Type | Default | Description |
|---|---|---|---|
data-stepper-active-step
|
number
|
1
|
Specifies the active step number when the stepper is first initialized, indicating which step should be active at the start. |
data-stepper-hidden-class
|
string
|
"hidden"
|
Defines a Tailwind CSS class applied to hide the stepper contents when they are not active. |
Utilities
Manage and interact with KTStepper instances using these static methods of
KTStepper
class.
| Method | Description |
|---|---|
init()
|
Automatically initializes KTStepper object for all elements with the
data-stepper="true"
attribute on page load.
|
createInstances()
|
Allows to create KTStepper instances for all elements that have been dynamically added to the DOM but haven't been activated yet. |
getInstance(element)
|
Returns the
KTStepper
object associated with the given DOM element
element
.
|
getOrCreateInstance(element)
|
Returns the existing
KTStepper
object for the provided DOM element
element
, or creates a new instance if none exists, then returns the same.
|
// Initialize all steppers
KTStepper.init()
// Initialzie pending steppers
KTStepper.createInstances();
// Get stepper object
const stepperEl = document.querySelector('#my_stepper');
const stepper = KTStepper.getInstance(stepperEl);
<div data-stepper="true" data-stepper-active-step="1" id="my_stepper">
...
</div>
Methods
Use KTStepper component's API methods to programmatically control its behavior.
| Method | Description |
|---|---|
new KTStepper(element, options)
|
Creates an object instance of the KTStepper class for the given DOM element and configuration options. |
go(step)
|
Navigates to the step with the specified step number in the stepper sequence. |
goTo(itemElement)
|
Navigates to the stepper item associated with the specified DOM element object. |
goFirst()
|
Navigates to the first step in the stepper sequence. |
goLast()
|
Navigates to the last step in the stepper sequence. |
goNext()
|
Moves the stepper to the next step in the sequence. |
goBack()
|
Moves the stepper to the previous step in the sequence. |
update()
|
Updates the stepper layout and state to reflect any changes in the DOM or stepper configuration. |
getStep(itemElement)
|
Returns the step number associated with the specified DOM element object. |
getItemElement(step)
|
Returns the DOM element object associated with the specified step number. |
getTotalSteps()
|
Returns the total number of steps in the stepper sequence. |
getItemElements()
|
Returns an array of all the DOM element objects in the stepper sequence. |
getOption(name)
|
Retrieves the value of a configuration option by
name
parameter from a KTStepper instance.
|
getElement()
|
Retrieves the DOM element linked to a specific KTStepper instance. |
on(eventName, handler)
|
Allows attaching event listeners to the KTStepper custom events using the
eventName
and
eventId
string parameters. These events enable programmatic interaction based on user actions or
internal state changes of KTStepper. The function returns
string
as a unique identifier for the registered listener, allowing you to remove it later if needed.
|
off(eventName, eventId)
|
Removes an event listener for the
eventName
and
eventId
parameters attached with the
on
method.
|
dispose()
|
Removes the KTStepper instance from an element, including any associated data stored on the DOM element. |
const stepperEl = document.querySelector('#my_stepper');
const stepper = KTStepper.getInstance(stepperEl);
stepper.goNext();
stepper.go(3);
<div data-stepper="true" data-stepper-active-step="1" id="my_stepper">
...
</div>
Events
KTStepper
custom events allows you to register callback functions(event listeners)
that will be invoked automatically whenever specific custom events are triggered within the component.
| Event | Description |
|---|---|
change
|
This event triggers before a stepper step is changed, allowing actions to be performed prior to the step transition. |
changed
|
This event triggers after a stepper step has changed, providing a hook to execute actions following the step transition. |
const stepperEl = document.querySelector('#my_stepper');
const stepper = KTStepper.getInstance(stepperEl);
stepper.on('change', (detail) => {
detail.cancel = true;
console.log('change action canceled');
});
stepper.on('changed', () => {
console.log('changed event');
});