Navigation Back to home

WizardNavigation

A vertical step-by-step navigation component for wizards.

Import
the javascript logo
import { WizardNavigation } from "@schukai/monster/source/components/navigation/wizard-navigation.mjs";
Source
the git logo
Package
the npm logo
Since
4.26.0
  1. Verify company
    • Company type
    • Company data
    • Company representative
    • Business owners
    • Managing directors of the company
    • Managing directors
    • Public details
  2. Add bank
    • Bank account
    • Confirm bank connection
  3. Protect account
    • Set up 2FA
    • Change password
  4. Add extras
    • Review and submit
    • Tax information
    • Billing details
  5. Review and submit
    • Tax information
    • Billing details

Introduction

The <monster-wizard-navigation> component is a structured and visually enhanced step navigation interface designed for guiding users through multi-step processes or wizards. It provides an accessible and clear representation of steps, supports nested substeps, and integrates seamlessly with custom click logic via JavaScript actions.

Whether used for onboarding, multi-step forms, or process-driven workflows, this component improves clarity, progress tracking, and user interaction consistency.

Key Features

  • Step-by-step interface: Displays a vertical list of steps with clear numbering and visual separation.
  • Substep support: Steps can contain nested substeps, visually indented and stylized consistently.
  • Custom click actions: Easily define actions triggered when users click on a step, via the actions.click callback.
  • Slotted content: Step structure is provided via an <ol class="wizard-steps"> passed through a slot.
  • Shadow DOM encapsulation: Layout and styles are fully encapsulated, but extensible through part attributes.
  • Visual highlighting: The current active step is styled differently to guide user attention.

Improving the user experience

The <monster-wizard-navigation> component helps users understand their progress in a task by clearly presenting a sequence of steps. By visually distinguishing active steps and allowing substeps, it makes even complex processes feel manageable and structured.

This contributes to better engagement, fewer errors, and higher task completion rates in guided workflows such as setup wizards, surveys, and application forms.

Efficiency in the development process

Developers can easily integrate the wizard navigation by passing an ordered list through a named slot. The component automatically imports and renders this content within its internal structure. Logic hooks such as actions.click provide full control over what happens when a user clicks on a step.

As with all Monster.js components, configuration is available via the data-monster-options attribute, and the component adheres to Monster.js conventions for slotting, event handling, and encapsulation.

Wizard Navigation Simple

Javascript

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

HTML

/** this example does not use an extra html file **/

Stylesheet

/** no additional stylesheet is defined **/

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
number):(boolean|Promise)}
function(number,
undefined
actions.beforeStepChange - 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.