WizardNavigation

A step-by-step wizard navigation for multi-stage forms and guided setup flows.

Import

import { WizardNavigation } from "@schukai/monster/source/components/navigation/wizard-navigation.mjs";

Source

View source code

Package

@schukai/monster

Since

4.26.0

Verify company
- Company type
- Company data
- Company representative
- Business owners
- Managing directors of the company
- Managing directors
- Public details
Add bank
- Bank account
- Confirm bank connection
Protect account
- Set up 2FA
- Change password
Add extras
- Review and submit
- Tax information
- Billing details
Review and submit
- Tax information
- Billing details

Introduction

The Monster WizardNavigation component guides users through a fixed sequence of steps. Use it when setup, checkout or registration flows need visible progress and a clear sense of what comes next.

When to use WizardNavigation

Use it for linear multi-step flows: Account setup and guided forms are typical examples.
Use it when progress visibility matters: The user should always know the current step and remaining path.
Do not use it for free exploration: Non-linear content usually wants tabs or site navigation instead.

Wizard Navigation Simple

This example demonstrates the standalone wizard navigation with nested sub-steps and simple previous/next controls.

Javascript

/** this example does not use an extra script **/

HTML

<monster-wizard-navigation id="wizard-navigation-demo">
  <ol class="wizard-steps">
    <li class="step">
      Account
      <ul>
        <li>Profile</li>
        <li>Security</li>
      </ul>
    </li>
    <li class="step">
      Billing
      <ul>
        <li>Address</li>
        <li>Payment</li>
      </ul>
    </li>
    <li class="step">
      Finish
      <ul>
        <li>Review</li>
      </ul>
    </li>
  </ol>
</monster-wizard-navigation>

<div style="margin-top:1rem;display:flex;gap:0.5rem;flex-wrap:wrap;">
  <button onclick="document.getElementById('wizard-navigation-demo').previous()">
    Previous
  </button>
  <button onclick="document.getElementById('wizard-navigation-demo').next()">
    Next
  </button>
  <button onclick="document.getElementById('wizard-navigation-demo').completeAll()">
    Complete all
  </button>
</div>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

The <monster-wizard-navigation> component is built using the Shadow DOM to encapsulate its internal structure and styles. This prevents layout conflicts and ensures predictable visual behavior regardless of external styles.

Shadow DOM and Accessibility

The wizard navigation content is passed in via a <slot> and then imported into the component's shadow DOM. While the internal structure is isolated, the rendered steps remain semantically correct and accessible. Steps can be navigated via screen readers and clicked with keyboard or mouse.

Developers can assign semantic meaning to the slotted list using standard HTML markup like <ol>, <li>, and <span> for titles.

Customizing Through Exported Parts

The component exposes its outer container through a part attribute to support external styling. Individual steps and substeps are stylized using internal class names, but follow predictable CSS structure.

Available Part Attributes

control: Wraps the entire wizard navigation area.

Example: styling the control part and customizing step appearance via class names:

 monster-wizard-navigation::part(control) { padding: 1em; background-color:
    var(--monster-bg-color-primary-1); border-radius: 6px; } .wizard-steps .step-active .step-title { color:
    var(--monster-color-secondary-1); font-weight: bold; }

Explanation of the Example

::part(control): Adds spacing and background styling to the outer wizard container.
.step-active .step-title: Highlights the current step in the wizard sequence.

Accessibility

Accessibility is supported through semantic HTML structure. Since the component relies on a slotted <ol class="wizard-steps">, it retains the ordered structure natively understood by screen readers. Active steps are visually highlighted and can be announced via custom logic tied to the monster-wizard-navigation-clicked event.

The component emits events and exposes hooks to allow full integration with ARIA live regions, custom announcements, or keyboard navigation enhancements.

HTML Structure

<monster-wizard-navigation></monster-wizard-navigation>

JavaScript Initialization

const element = document.createElement('monster-wizard-navigation');
document.body.appendChild(element);

Exported

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

actions

object

Action callbacks

actions.beforeStepChange

function

undefined

Callback fired before a main step change. Must return `true` or a Promise that resolves to `true` to allow the transition. Parameters are `fromIndex` and `toIndex`.

actions.click

function

undefined

General click handler callback.

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Behavioral methods

next()

Navigates to the next step or sub-step in sequence.

previous()

Navigates to the previous step or sub-step in sequence.

Structural methods

getCurrentStepIndex()

Gets the index of the currently active main step.

getCurrentSubStepIndex()

Gets the index of the currently active sub-step within the main step.

Static methods

[instanceSymbol]()4.26.0

Events

monster-wizard-step-changed Fired when the main active step changes.
monster-wizard-substep-changed Fired when the active sub-step changes.
monster-wizard-completed Fired when the entire wizard is marked as complete via completeAll().

A WizardNavigation component to display progress and allow navigation through a series of steps, including support for nested sub-steps.

getCSSStyleSheet()

Gets the index of the currently active sub-step within the main step.

getTag()

Gets the index of the currently active sub-step within the main step.

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()4.26.0

Events

monster-wizard-step-changed Fired when the main active step changes.
monster-wizard-substep-changed Fired when the active sub-step changes.
monster-wizard-completed Fired when the entire wizard is marked as complete via completeAll().

A WizardNavigation component to display progress and allow navigation through a series of steps, including support for nested sub-steps.

Other methods

activate(mainIndex,subIndex,[options={}])

Parameters

mainIndex {number}: The index of the main step.
subIndex {number}: The index of the sub-step.
[options={}] {object}: Additional options.

Events

monster-wizard-substep-changed

Activates a specific main step and sub-step.

completeAll()

Events

monster-wizard-completed

Marks the entire wizard workflow as completed.

completeAndNext()

Marks the current step as completed and automatically navigates to the next step.

goToStep(index,[options={}])

Parameters

index {number}: The index of the target step.
[options={}] {object}: Additional options.

Events

monster-wizard-step-changed

Navigates to the specified main step if the transition logic allows it.

Events

The component emits the following events:

monster-wizard-step-changed
Fired when the main active step changes.
monster-wizard-substep-changed
Fired when the active sub-step changes.
monster-wizard-completed
Fired when the entire wizard is marked as complete via completeAll().
monster-wizard-step-changed
Fired when the main active step changes.
monster-wizard-substep-changed
Fired when the active sub-step changes.
monster-wizard-completed
Fired when the entire wizard is marked as complete via completeAll().
monster-wizard-step-changed
Fired when the main active step changes.
monster-wizard-substep-changed
Fired when the active sub-step changes.
monster-wizard-completed
Fired when the entire wizard is marked as complete via completeAll().
monster-wizard-step-changed
monster-wizard-substep-changed
monster-wizard-completed

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.