A library that implements to the Material Design Lite a polyfill of stepper component specified by Material Design.

MDL Stepper

A library that implements to the Material Design Lite a polyfill of stepper component specified by Material Design. The stepper polyfill will help you to implement this material design component today.

Navigation

• Get started
  • Installation
  • Basic usage
• Steppers
  • Linear stepper
  • Non-linear stepper
  • Stepper feedback
  • Linear stepper
  • Editable steps
  • Optional steps
  • Error state
• Introduction
  • To include a component
  • Configuration options
• Javascript API
  • Methods
  • Custom events
  • Component handler
  • MDL component design pattern
  • Dynamically adding a Stepper
• Development
  • Source
  • Javascript
  • CSS
• Why MDL Stepper
• License

Use MDL Stepper on your site?

ahlechandre.github.io/mdl-stepper

Get started

The MDL Stepper component was based on Material Design Lite (MDL) library. To use this component before you will need to include the MDL to your project.

Installation

Download (zip)

You can download the current version of repository compacted.

Build

# Clone the repository.
git clone git@github.com:ahlechandre/mdl-stepper.git
# Access created folder.
cd mdl-stepper

Goes to development section for details.

NPM

npm install --save mdl-stepper

Bower

bower install mdl-stepper

Basic usage

1. Choose the type of download and include the Material Design Lite files to your all pages.

2. Get the CSS & Javascript files of MDL Stepper component.

3. Include the Material Design Lite + Stepper files.

CSS & Icons

<!-- Material Design Lite CSS -->
<link rel="stylesheet" href="https://code.getmdl.io/1.1.3/material.blue-pink.min.css" />
<!-- MDL Stepper CSS -->
<link rel="stylesheet" href="./stepper.min.css">
<!-- Material Icons -->
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">

Javascript

Note: Make sure that you are loading the javascripts in the correct order.

<!-- Material Design Lite JS -->
<script defer src="https://code.getmdl.io/1.1.3/material.min.js"></script>
<!-- MDL Component JS -->
<script defer src="./stepper.min.js"></script>
<script>
  (function () {
    window.addEventListener('load', function () {
      // Your custom code in "onload" callback.
    });
  })();
</script>

Component

// Select your stepper element.  
var stepperElement = document.querySelector('ul.mdl-stepper');
// Get the instance of componet for control over API.
var Stepper = stepperElement.MaterialStepper;
// Goes to the next step.
Stepper.next();

Steppers

The types of steppers and steps are specified in Material Design page.

Linear stepper

Linear steppers require users to complete one step in order to move on to the next. (Material Design)

Non-linear stepper

Non-linear steppers allow users to enter a multi-step flow at any point. (Material Design)

Stepper feedback

Steppers may display a transient feedback message after a step is saved. Stepper feedback should only be used if there is a long latency between steps. (Material Design)

Editable steps

Editable steps allow users to return later to edit a step. These are ideal for workflows that involve editing steps within a session. (Material Design)

Optional steps

Optional steps within a linear flow should be marked as optional. (Material Design)

Error state

Introduction

“Steppers display progress through a sequence by breaking it up into multiple logical and numbered steps. Avoid using steppers to break up sections in a short form, or multiple times on one page”. Goes to Material Design spec page.

To include a component

See component markup details.

Configuration options

Javascript API

Methods and custom events to the control over Stepper instance.

Methods

Custom Events

Component handler

The Stepper follows MDL component design pattern and uses the component handler to register and upgrades the component.

if (typeof window.componentHandler !== 'undefined') {
  // componentHandler is sucessfully loaded and available globally.
}

MDL component design pattern

A design pattern that elegantly handles the registration of new components such that DOM upgrades are automatically performed on document load, as well as making it super easy to handle upgrades of elements that may be added after initial page load. It even ensures elements can never be “double” (or more) upgraded, whilst allowing any HTMLElement to be upgraded to multiple component types.

Dynamically adding a Stepper

If you need to include a Stepper after initial page load (by an asynchronous request for example), you will have to manually upgrades the component.

// Gets your stepper element added after initial page load.
var stepperElement = document.querySelector('.mdl-stepper');

// The component instance is not upgraded and so not defined.
console.log(typeof stepperElement.MaterialStepper); // undefined

// Upgrades all registered components found in the current DOM. 
// This is automatically called on window load.
componentHandler.upgradeAllRegistered();

// At this point, component handler already upgraded
// the Stepper component and assigned the instance for 
// control over API.
console.log(typeof stepperElement.MaterialStepper); // object

Instead of upgrade all registered (recommended) you can upgrade only the Stepper element using:

// Gets your stepper element added after initial page load.
var stepperElement = document.querySelector('.mdl-stepper');

// Upgrades a specific element rather than all in the DOM.
componentHandler.upgradeElement(stepperElement);

Development

Source

# Clone the repository.
git clone git@github.com:ahlechandre/mdl-stepper.git
# Access created folder.
cd mdl-stepper

Javascript

# Inside mdl-stepper/ folder.
# Install dev dependencies.
npm install
# Build a development version of javascript changes.
npm run dev
# Build a production version of javascript changes.
npm run prod
# Build a production version of javascript changes on WINDOWS.
# npm run prod-windows

CSS

# First, make sure that you have SASS installed (http://sass-lang.com/install).
sass --version
# $ Sass x.x.x
# Inside mdl-stepper/ folder.
cd src
# ~/mdl-stepper/src
# Build a development version of css changes.
sass mdl-stepper.scss:../stepper.css
# Build a production version of css changes.
sass mdl-stepper.scss:../stepper.min.css --style compressed

Why MDL Stepper

As discussed at #1748 issue, the stepper is a component that is present in the Material Design specification and MDL has not support yet.

While the Material Design Lite team works in other parts of the library, i decided to create my own component.

Obviously, this is my interpretation of the spec and it does not reflect what the Material Design team would consider ‘correct’ but i tried to preserve as much of specified details.

You can consider this as a polyfill to be used while the MDL do not include that. Maybe it can be useful and help other people to build their web apps.

License

MIT License © 2016 Alexandre Thebaldi