jQuery Smart Wizard

To use SmartWizard, you must follow a specific HTML structure consisting of a navigation list (ul.nav) and a content container (div.tab-content).

1. Navigation: A ul with class nav containing li.nav-item elements. Each item should have an a.nav-link with an href pointing to the step ID.
2. Content: A div.tab-content containing div.tab-pane elements with IDs matching the navigation links.
3. Progress Bar (Optional): A div.progress containing a div.progress-bar.

<!-- SmartWizard HTML Structure -->
<div id="smartwizard">
    <ul class="nav">
        <li class="nav-item">
          <a class="nav-link" href="#step-1">
            <div class="badge">1</div>
            Step Title
          </a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#step-2">
            <span class="badge">2</span>
            Step Title
          </a>
        </li>
    </ul>

    <div class="tab-content">
        <div id="step-1" class="tab-pane" role="tabpanel" aria-labelledby="step-1">
            Step 1 content
        </div>
        <div id="step-2" class="tab-pane" role="tabpanel" aria-labelledby="step-2">
            Step 2 content
        </div>
    </div>

    <!-- Optional progressbar -->
    <div class="progress">
      <div class="progress-bar" role="progressbar" style="width: 0%" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100"></div>
    </div>
</div>

Initialize the wizard with an options object to control behavior, themes, transitions, and navigation.

Key Configuration Groups:

• initialStep: Index of the first step (default 0).
• theme: Visual style (basic | arrows | dots | round | square | progress).
• displayMode: auto | dark | light | none.
• behavior: Includes autoHeight and useUrlHash.
• navigation: Controls anchor clicks and completed step behavior.
• transition: Defines animation effect (default | fade | slideHorizontal | slideVertical | slideSwing | css), speed, and easing.
• toolbar: Position and button visibility (showNext, showPrevious).
• stepStates: Pre-set states for steps (completed, disabled, hidden, error, warning).
• contentLoader: A callback function for dynamic content loading.

$('#smartwizard').smartWizard({
    initialStep: 0,
    theme: 'basic',
    displayMode: 'auto',
    behavior: {
        autoHeight: true,
        useUrlHash: false,
        supportBrowserHistory: false
    },
    navigation: {
        enabled: true,
        alwaysClickable: false,
        completed: {
            enabled: true,
            completeAllPreviousSteps: true,
            clearOnBack: false,
            clickable: true
        }
    },
    transition: {
        effect: 'default',
        speed: 400,
        easing: '',
        css: {
            prefix: '',
            forward:  { show: '', hide: '' },
            backward: { show: '', hide: '' }
        }
    },
    toolbar: {
        position: 'bottom',
        buttons: {
            showNext: true,
            showPrevious: true
        },
        extraElements: ''
    },
    keyboardNavigation: {
        enabled: true,
        keys: {
            left: [37],
            right: [39]
        }
    },
    swipeNavigation: {
        enabled: false,
        threshold: 50
    },
    localization: {
        buttons: {
            next: 'Next',
            previous: 'Previous'
        }
    },
    stepStates: {
        completed: [],
        disabled: [],
        hidden: [],
        error: [],
        warning: []
    },
    scrollToView: false,
    contentLoader: null
});

Options in v7 are restructured into logical groups. Below is the mapping for common configuration changes from v6 to v7.

$('#smartwizard').smartWizard({
    initialStep: 0,
    theme: 'arrows',
    displayMode: 'auto', // NEW: 'auto' | 'dark' | 'light' | 'none'
    behavior: {
        autoHeight: true,
        supportBrowserHistory: true,
        useUrlHash: false,
    },
    transition: {
        effect: 'css',
        speed: 400,
        easing: '',
        css: {
            prefix: 'animate__animated',
            forward:  { show: 'animate__fadeIn',  hide: 'animate__fadeOut' },
            backward: { show: 'animate__fadeIn',  hide: 'animate__fadeOut' },
        },
    },
    toolbar: {
        position: 'bottom',
        buttons: {
            showNext: true,
            showPrevious: true,
        },
        extraElements: '<button>Custom</button>',
    },
    navigation: {
        enabled: true,
        alwaysClickable: false,
        completed: {
            enabled: true,
            completeAllPreviousSteps: true,
            clearOnBack: false,
            clickable: true,
        },
    },
    keyboardNavigation: {
        enabled: true,
        keys: {
            left: [37],
            right: [39],
        },
    },
    swipeNavigation: {  // NEW
        enabled: false,
        threshold: 50,
    },
    localization: {
        buttons: {
            next: 'Next',
            previous: 'Previous',
        },
    },
    stepStates: {
        disabled: [2],
        error: [],
        warning: [],
        hidden: [],
        completed: [],
    },
    contentLoader: null,
});

Control the wizard instance using the .smartWizard() jQuery method with specific command strings.

Navigation Methods:

• next: Navigate to the next step.
• prev: Navigate to the previous step.
• goToStep, index: Go to a specific step index.
• goToStep, index, true: Force navigation to a step and mark previous steps as done.
• reset: Reset the wizard to its initial state.

State and Configuration Methods:

• setOptions, options: Update configuration at runtime.
• setState, [indexes], state: Set state for steps (e.g., 'disable', 'error').
• unsetState, [indexes], state: Remove a state from steps.
• loader, 'show' | 'hide': Toggle the loading indicator.
• adjustHeight: Manually trigger content height adjustment.
• getStepInfo: Returns { currentStep, totalSteps }.

const wizard = $('#smartwizard');

wizard.smartWizard('next');
wizard.smartWizard('prev');
wizard.smartWizard('goToStep', 2);
wizard.smartWizard('goToStep', 2, true);
wizard.smartWizard('reset');
wizard.smartWizard('setOptions', { theme: 'arrows' });

wizard.smartWizard('setState', [1, 2], 'disable');
wizard.smartWizard('setState', [3], 'error');
wizard.smartWizard('unsetState', [1, 2], 'disable');

wizard.smartWizard('loader', 'show');
wizard.smartWizard('loader', 'hide');

wizard.smartWizard('adjustHeight');

const info = wizard.smartWizard('getStepInfo');

Listen to lifecycle events to implement custom logic, such as form validation or post-step actions.

Available Events:

• initialized.sw: Fires after the wizard is fully initialized.
• loaded.sw: Fires after the initial step is shown for the first time.
• leave.sw: Fires before leaving the current step. Note: Returning false from the handler will cancel navigation.
  • Arguments: { stepIndex, nextStepIndex, stepElement, stepDirection, stepPosition }.
• shown.sw: Fires after a new step is shown.
  • Arguments: { stepIndex, stepElement, stepDirection, stepPosition }.

// Example: Prevent navigation if validation fails
$('#smartwizard').on('leave.sw', function(e, args) {
    const isValid = validateCurrentStep();
    if (!isValid) {
        return false; // Cancel navigation
    }
});

// Example: React to step being shown
$('#smartwizard').on('shown.sw', function(e, args) {
    console.log('Step shown:', args.stepIndex);
});