VanillaJS Smart Wizard

The awesome step wizard plugin for VanillaJS

If you want to contribute to the original author click here: Original project

VanillaJS Smart Wizard is a step wizard plugin that does not require jQuery and is written in pure JavaScript. Its purpose is to provide a clean, elegant, and functional user interface for processes such as forms, checkouts, and registrations.

The project has been completely rewritten to remove the jQuery dependency, making it lighter, faster, and more modern. It supports ESM and CommonJS and works in all modern browsers. Additionally, it is designed with a responsive approach and is compatible with Bootstrap.

Main Features

• No jQuery: Works with pure JavaScript, making it faster and lighter.
• Easy to Implement: Requires minimal HTML to work.
• Responsive Design: Adapts to all devices and is compatible with Bootstrap.
• Field Validation: Allows validating required fields when moving between steps, with the option for custom events and error handling functions.
• Transitions: Includes transition animations like fade, slideHorizontal, slideVertical, and slideSwing.
• CSS Animation Support: Easily extendable with custom animations and compatible with libraries like Animate.css.
• Dynamic Content: Allows integration of content through Ajax.
• Customizable Controls: Includes a built-in toolbar, progress bar, and loader.
• RTL Support: Ready for right-to-left languages.
• Accessibility: Provides accessible controls for a better user experience.

Installation & Usage

The plugin is compatible with the main JavaScript module systems, making it easy to integrate into any modern project. Below are initialization examples for ESM (ECMAScript Modules) and CommonJS.

Initialization with ES Modules (ESM)

For projects using a bundler like Vite, Webpack, or Rollup, the ESM approach is the most common. First, make sure the plugin is installed in your project.

import SmartWizard from 'vanillajs-smartwizard';
import 'vanillajs-smartwizard/css'; // Or the direct path depending on the bundler

// Wizard initialization
const wizard = new SmartWizard('#smartwizard', {
    selected: 0,
    theme: 'arrows', // Example custom theme
    toolbar: {
        position: 'bottom',
    },
    // Other options...
});

// Example of using a public method
document.getElementById('nextButton').addEventListener('click', () => {
    wizard.next();
});

Initialization with CommonJS

/** Common JS **/
const SmartWizard = require('vanillajs-smartwizard');
/**
 * 
 * Remember, you must import de CSS file
 * 
 * 
 */
// Make sure the HTML is loaded before initializing
document.addEventListener('DOMContentLoaded', () => {
    // Wizard initialization
    const wizard = new SmartWizard('#smartwizard', {
        selected: 0,
        theme: 'arrows',
    });

    // Example of use
    document.getElementById('prevButton').addEventListener('click', () => {
        wizard.prev();
    });
});

Initialization with CDN/HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/vanillajs.smartWizard.min.css">
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/vanillajs.smartWizard.umd.min.js"></script>

Configuration Options

| Option | Type | Default Value | Description | | :---------------------- | :-------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | debug | boolean | false | Enables debug messages in the console. | | initAtCreated | boolean | true | Whether the wizard initializes automatically when created. | | selected | number | 0 | The index of the step selected at start. | | theme | string | 'basic' | The wizard theme (e.g., 'basic'). | | justified | boolean | true | Whether navigation steps are justified to take full width. | | autoAdjustHeight | boolean | true | Whether the wizard auto-adjusts its height to the content. | | backButtonSupport | boolean | true | Enables browser back button navigation. | | enableUrlHash | boolean | true | Enables using the URL hash for step navigation. | | transition | object | See source code | Transition animation settings. Includes animation (e.g., 'fade') and speed (ms). | | toolbar | object | See source code | Toolbar settings. Includes position ('top', 'bottom', 'both'), showNextButton, and showPreviousButton. | | keyboard | object | See source code | Keyboard navigation settings. Includes keyNavigation, keyLeft, and keyRight. | | lang | object | See source code | Allows customizing button texts. | | style | object | See source code | Defines CSS classes for wizard elements. | | disabledSteps | array | [] | Array of step indices to disable. | | errorSteps | array | [] | Array of step indices marked with an error state. | | hiddenSteps | array | [] | Array of step indices to hide. | | requiredField | object | See source code | Options for required field validation. Includes active, checkOnSubmitForm, controls, classInvalid, and functionToValidate. |

Public Methods (API)

| Method | Description | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------- | | goToStep(stepIndex, force) | Navigates to the specified step by stepIndex. The optional force parameter forces navigation. | | next() | Navigates to the next available step. | | prev() | Navigates to the previous available step. | | reset() | Resets the wizard to its initial state. | | setState(stepArray, state) | Sets a state (e.g., 'error', 'done') for the specified steps. | | unsetState(stepArray, state) | Removes a state from the specified steps. | | unsetErrors(idx) | Removes the error state of a specific step. | | setOptions(options) | Updates the wizard configuration with the provided options. | | getOptions() | Returns the current wizard configuration. | | getStepInfo() | Returns an object with current state info, including current step (currentStep) and total steps (totalSteps). | | loader(state) | Shows or hides the wizard loader. The state can be 'show' or 'hide'. | | fixHeight() | Forces the container to readjust its height. | | init() | Initializes the wizard if initAtCreated is false. | | checkStepRequired(step) | Validates required fields of a specific step. Returns true if there are errors, false otherwise. | | checkFormRequireds() | Validates all required fields in the form. Returns true if there are errors. | | destroy() | Removes all events and configuration, destroying the wizard instance. |

License

MIT License