The m3e-stepper component provides a wizard-like workflow by dividing content into logical steps.

npm i @m3e/stepper

This section outlines usage examples and configuration guidance for the components in this package.

Use m3e-stepper, m3e-step, and m3e-step-panel to construct a wizard-like workflow. Both m3e-step and m3e-step-panel must be direct children of m3e-stepper. To associate a step with its corresponding panel, set the for attribute on m3e-step to match the ID of the target m3e-step-panel.

To select a step, apply the selected attribute to a single m3e-step. When a step is activated, a cancellable input event is emitted followed by a change event. To cancel selection change, call preventDefault during input. Only one step may be selected at a time.

<m3e-stepper>
  <m3e-step for="step1">Fill out your name</m3e-step>
  <m3e-step for="step2">Fill out your address</m3e-step>
  <m3e-step for="step3">Done</m3e-step>
  <m3e-step-panel id="step1">
    <form>
      <m3e-form-field>
        <label slot="label" for="name">Name</label>
        <input name="name" id="name" required />
      </m3e-form-field>
    </form>
    <div slot="actions">
      <m3e-button><m3e-stepper-next>Next</m3e-stepper-next></m3e-button>
    </div>
  </m3e-step-panel>
  <m3e-step-panel id="step2">
    <form>
      <m3e-form-field>
        <label slot="label" for="address">Address</label>
        <input name="address" id="address" required />
      </m3e-form-field>
    </form>
    <div slot="actions">
      <m3e-button><m3e-stepper-previous>Back</m3e-stepper-previous></m3e-button>
      <m3e-button><m3e-stepper-next>Next</m3e-stepper-next></m3e-button>
    </div>
  </m3e-step-panel>
  <m3e-step-panel id="step3">
    Done
    <div slot="actions">
      <m3e-button><m3e-stepper-previous>Back</m3e-stepper-previous></m3e-button>
      <m3e-button><m3e-stepper-reset>Reset</m3e-stepper-reset></m3e-button>
    </div>
  </m3e-step-panel>
</m3e-stepper>

The m3e-stepper supports three orientations: horizontal (default), vertical, and auto. Using auto, the orientation is responsive and determined by viewport size. Use the orientation attribute to change a stepper's orientation.

<m3e-stepper orientation="vertical">
  <!-- Content omitted for brevity -->
</m3e-stepper>

When using a horizontal stepper, you can control where the stepper's content is positioned using the header-position attribute. By default, the header is placed above content, but you can change it to below to placed it under the content.

<m3e-stepper header-position="below">
  <!-- Content omitted for brevity -->
</m3e-stepper>

When using a horizontal stepper, you can control where the step's label is positioned using the label-position attribute. By default, labels are placed after a step's icon, but you can change it to below to placed it under the icon.

<m3e-stepper label-position="below">
  <!-- Content omitted for brevity -->
</m3e-stepper>

Panels provide an actions slot for placing navigation controls. The m3e-stepper-previous, m3e-stepper-next, and m3e-stepper-reset components can be used to navigate steps. Using the m3e-stepper-reset will reset the stepper and any form data.

<m3e-step-panel>
  <div slot="actions">
    <m3e-button><m3e-stepper-previous>Back</m3e-stepper-previous></m3e-button>
    <m3e-button><m3e-stepper-next>Next</m3e-stepper-next></m3e-button>
  </div>
</m3e-step-panel>

The linear attribute can be set on m3e-stepper to create a linear stepper that requires the user to complete previous steps before proceeding to following steps.

Linear steppers require use of a form per step whose validity status determines whether a user can move to the next step.

<m3e-stepper linear>
  <!-- Content omitted for brevity -->
</m3e-stepper>

Use the optional attribute on m3e-step to indicate that completion is not required. When navigating away from an optional step, its nested form is still validated; however, an invalid state will neither block progression nor visually mark the step header as invalid.

For linear steppers, use the editable attribute on m3e-step to allow a user to navigate back to a previously completed step.

You can use the completed and invalid attributes to programmatically control whether a step is completed or invalid.

You can override icons using the icon, done-icon, edit-icon, and error-icon.

You can use the hint and error slots of a m3e-step to specify hint text or, when invalid, an error message. By default, optional steps have hint text of (Optional).

Steppers implement the ARIA Tabs design pattern and are composed of the tablist, tab, and tabpanel roles. The pattern includes support for keyboard navigation, focus management, and accessible relationships between steps and their associated panels.

The m3e-stepper component hosts an internal tablist. It contains each m3e-step, which is assigned the ARIA role="tab". Corresponding m3e-step-panel elements are given the ARIA role="tabpanel". Each step is linked to its associated panel using aria-controls, and the aria-selected attribute communicates the selected state of a step to assistive technologies. When a step is disabled, aria-disabled="true" communicates its inactive state.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/stepper/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js",
      "@m3e/core/layout": "/node_modules/@m3e/core/dist/layout.js"
    }
  }
</script>

For production, use index.min.js, a11y.min.js and layout.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.