Stepper

Stepper Layout

Single stepper layout is pretty simple:

<!-- Stepper element -->
<div class="stepper">
  <!-- Stepper minus/decrement button -->
  <div class="stepper-button-minus"></div>
  <!-- Stepper input -->
  <div class="stepper-input-wrap">
    <!-- recommended to make input not editable (readonly) -->
    <input type="text" readonly value="10">
  </div>
  <!-- Stepper plus/increment button -->
  <div class="stepper-button-plus"></div>
</div>

If you don't need an input element but still need to keep the value:

<!-- Stepper element -->
<div class="stepper">
  <div class="stepper-button-minus"></div>
  <!-- Stepper value element -->
  <div class="stepper-value">10</div>
  <div class="stepper-button-plus"></div>
</div>

And if you don't need to display value between stepper buttons:

<!-- Stepper element -->
<div class="stepper">
  <div class="stepper-button-minus"></div>
  <div class="stepper-button-plus"></div>
</div>

Stepper Modifier Classes

Similar to Button it is possible to change Stepper styles (shape, size and color) by using additional modifier classes:

stepper-fill Filled-style stepper buttons
stepper-fill-ios Stepper buttons will have filled-style only in iOS theme
stepper-fill-md Stepper buttons will have filled-style only in MD theme
stepper-round Rounded stepper buttons
stepper-round-ios Stepper buttons will be rounded only in iOS theme
stepper-round-md Stepper buttons will be rounded only in MD theme
stepper-small Small stepper
stepper-small-ios Stepper will be small only in iOS theme
stepper-small-md Stepper will be small only in MD theme
stepper-big Big stepper
stepper-big-ios Stepper will be big only in iOS theme
stepper-big-md Stepper will be big only in MD theme
stepper-raised Raised stepper This will have effect only in MD theme
color-[color] Color button, where [color] is one of the default colors

Stepper App Methods

Let's look at related App methods to work with Stepper:

app.stepper.create(parameters)- create Stepper instance

  • parameters - object. Object with stepper parameters

Method returns created Stepper's instance

app.stepper.destroy(el)- destroy Stepper instance

  • el - HTMLElement or string (with CSS Selector) or object. Stepper element or Stepper instance to destroy.

app.stepper.get(el)- get Stepper instance by HTML element

  • el - HTMLElement or string (with CSS Selector). Stepper element.

Method returns Stepper's instance

app.stepper.getValue(el)- get Stepper value

  • el - HTMLElement or string (with CSS Selector). Stepper element.

Method returns stepper value

app.stepper.setValue(el, value)- set new Stepper value

  • el - HTMLElement or string (with CSS Selector). Stepper element.
  • value - number

Method returns Stepper's instance

Stepper Parameters

Now let's look at list of available parameters we need to create Stepper:

Parameter Type Default Description
el HTMLElement
string
Stepper element. HTMLElement or string with CSS selector of stepper element
inputEl HTMLElement
string
Stepper input element or CSS selector of input element. If not specified, will try to look for <input> inside of stepper element
step number 1 Minimal step between values
min number 0 Minimum value
max number 100 Maximum value
value number 0 Initial value
wraps boolean false When enabled, incrementing beyond maximum value sets value to minimum value; likewise, decrementing below minimum value sets value to maximum value
autorepeat boolean false When enabled it will repeatedly increase/decrease values while you tap and hold plus/minus buttons
autorepeatDynamic boolean false When enabled it will increase autorepeat ratio based on how long you hold the button
valueEl HTMLElement
string
Stepper value element or CSS selector of this element where Stepper will insert value. If not specified, and there is no inputEl passed will try to look for <div class="stepper-value"> inside of stepper element
formatValue function (value) Function to format value in required format. It accepts current value and must return new formatted value;
on object Object with events handlers. For example:
var stepper = app.stepper.create({
  el: '.stepper'
  on: {
    change: function () {
      console.log('Stepper value changed')
    }
  }
})

Stepper Methods & Properties

So to create Stepper we have to call:

var stepper = app.stepper.create({ /* parameters */ })

After that we have its initialized instance (like stepper variable in example above) with useful methods and properties:

Properties
stepper.app Link to global app instance
stepper.el Stepper HTML element
stepper.$el Dom7 instance with stepper HTML element
stepper.min Stepper min value
stepper.max Stepper max value
stepper.value Stepper value
stepper.inputEl Stepper input HTML element
stepper.$inputEl Dom7 instance with stepper input HTML element
stepper.valueEl Stepper value container HTML element
stepper.$valueEl Dom7 instance with stepper value container HTML element
stepper.params Stepper parameters
Methods
stepper.getValue() Returns stepper value
stepper.setValue(value) Set new stepper value
stepper.increment() Increment stepper value, similar to clicking on its "plus" button
stepper.decrement() Decrement stepper value, similar to clicking on its "minus" button
stepper.plus() Alias for stepper.increment()
stepper.minus() Alias for stepper.decrement()
stepper.destroy() Destroys stepper instance
stepper.on(event, handler) Add event handler
stepper.once(event, handler) Add event handler that will be removed after it was fired
stepper.off(event, handler) Remove event handler
stepper.off(event) Remove all handlers for specified event
stepper.emit(event, ...args) Fire event on instance

Stepper Events

Stepper will fire the following DOM events on stepper element and events on app and stepper instance:

DOM Events

Event Target Description
stepper:change Stepper Element<div class="stepper"> Event will be triggered when Stepper value has been changed
stepper:beforedestroy Stepper Element<div class="stepper"> Event will be triggered right before Stepper instance will be destroyed

App and Stepper Instance Events

Stepper instance emits events on both self instance and app instance. App instance events has same names prefixed with stepper.

Event Arguments Target Description
change (stepper, value) stepper Event will be triggered when stepper value has been changed. As an argument event handler receives stepper instance and stepper value
stepperChange (stepper, value) app
beforeDestroy (stepper) stepper Event will be triggered right before Stepper instance will be destroyed. As an argument event handler receives stepper instance
stepperBeforeDestroy (stepper) app

Stepper Auto Initialization

If you don't need to use Stepper API and your Stepper is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional stepper-init class:

<!-- Add stepper-init class -->
<div class="stepper stepper-init">
  <div class="stepper-button-minus"></div>
  <div class="stepper-input-wrap">
    <input type="text" readonly>
  </div>
  <div class="stepper-button-plus"></div>
</div>

In this case if you need to access created Stepper instance you can use the app.stepper.get app method:

var stepper = app.stepper.get('.stepper');

if (stepper.value > 50) {
  // do something
}

When using auto init you may need to pass additional parameters. It can be done with two ways:

  • If you use stepper with input then step, min, max, value parameters can be set from same input attributes:

    <!-- min, max, step, value parameters will be set for same input attributes -->
    <div class="stepper stepper-init">
      <div class="stepper-button-minus"></div>
      <div class="stepper-input-wrap">
        <input type="text" readonly min="0" max="50" step="10" value="15">
      </div>
      <div class="stepper-button-plus"></div>
    </div>
  • Otherwise, if you don't have input inside, you can set all available parameters via data- attributes on stepper element.

    <!-- parameters set via data- attributes -->
    <div
      class="stepper stepper-init"
      data-min="0"
      data-max="500"
      data-step="25"
      data-value="75"
    >
      <div class="stepper-button-minus"></div>
      <div class="stepper-value"></div>
      <div class="stepper-button-plus"></div>
    </div>
    

Examples

Shape and size

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <small>Default</small>
      <div class="stepper stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Round</small>
      <div class="stepper stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Fill</small>
      <div class="stepper stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Round Fill</small>
      <div class="stepper stepper-fill stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Small</small>
      <div class="stepper stepper-small stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Small Round</small>
      <div class="stepper stepper-small stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Small Fill</small>
      <div class="stepper stepper-small stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Small Round Fill</small>
      <div class="stepper stepper-small stepper-round stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Big</small>
      <div class="stepper stepper-big stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Big Round</small>
      <div class="stepper stepper-big stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Big Fill</small>
      <div class="stepper stepper-big stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Big Round Fill</small>
      <div class="stepper stepper-big stepper-round stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Raised (MD-theme only)

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <small>Default</small>
      <div class="stepper stepper-raised stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Round</small>
      <div class="stepper stepper-raised stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Fill</small>
      <div class="stepper stepper-raised stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Round Fill</small>
      <div class="stepper stepper-raised stepper-fill stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Small</small>
      <div class="stepper stepper-raised stepper-small stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Small Round</small>
      <div class="stepper stepper-raised stepper-small stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Small Fill</small>
      <div class="stepper stepper-raised stepper-small stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Small Round Fill</small>
      <div class="stepper stepper-raised stepper-small stepper-round stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Big</small>
      <div class="stepper stepper-raised stepper-big stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Big Round</small>
      <div class="stepper stepper-raised stepper-big stepper-round stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <small>Big Fill</small>
      <div class="stepper stepper-raised stepper-big stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Big Round Fill</small>
      <div class="stepper stepper-raised stepper-big stepper-round stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Colors

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <div class="stepper stepper-init stepper-fill color-red">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-round stepper-fill stepper-init color-green">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <div class="stepper stepper-fill stepper-init color-blue">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-fill stepper-round stepper-init color-pink">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <div class="stepper stepper-small stepper-fill stepper-init color-yellow">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-small stepper-fill stepper-round stepper-init color-orange">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>

  <div class="row margin-top">
    <div class="col">
      <div class="stepper stepper-small stepper-fill stepper-init color-gray">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-small stepper-round stepper-fill stepper-init color-black">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Without input element

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <div class="stepper stepper-init" data-value="0" data-min="0" data-max="100" data-step="1">
        <div class="stepper-button-minus"></div>
        <div class="stepper-value"></div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-round stepper-init" data-value="0" data-min="0" data-max="100" data-step="1">
        <div class="stepper-button-minus"></div>
        <div class="stepper-value"></div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Custom min, max and step

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <div class="stepper stepper-fill stepper-init">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="100" min="0" max="1000" step="100" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <div class="stepper stepper-fill stepper-round stepper-init" data-value="5" data-min="0" data-max="10" data-step="0.5">
        <div class="stepper-button-minus"></div>
        <div class="stepper-value"></div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Autorepeat (Tap & hold)

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <small>Default</small>
      <div class="stepper stepper-fill stepper-init" data-autorepeat="true">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
    <div class="col">
      <small>Dynamic</small>
      <div class="stepper stepper-fill stepper-init" data-autorepeat="true" data-autorepeat-dynamic="true">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="100" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Wraps

In wraps mode incrementing beyond maximum value sets value to minimum value, likewise, decrementing below minimum value sets value to maximum value

<div class="block block-strong text-align-center">
  <div class="row">
    <div class="col">
      <div class="stepper stepper-fill stepper-init" data-wraps="true" data-autorepeat="true" data-autorepeat-dynamic="true">
        <div class="stepper-button-minus"></div>
        <div class="stepper-input-wrap">
          <input type="text" value="0" min="0" max="10" step="1" readonly>
        </div>
        <div class="stepper-button-plus"></div>
      </div>
    </div>
  </div>
</div>

Custom value element

<div class="list">
  <ul>
    <li class="item-content">
      <div class="item-inner">
        <div class="item-title">Apples: <span id="apples-count"></span></div>
        <div class="item-after">
          <div class="stepper stepper-init stepper-small stepper-raised" data-value-el="#apples-count">
            <div class="stepper-button-minus"></div>
            <div class="stepper-button-plus"></div>
          </div>
        </div>
      </div>
    </li>
    <li class="item-content">
      <div class="item-inner">
        <div class="item-title">Oranges: <span id="oranges-count"></span></div>
        <div class="item-after">
          <div class="stepper stepper-init stepper-small stepper-raised" data-value-el="#oranges-count">
            <div class="stepper-button-minus"></div>
            <div class="stepper-button-plus"></div>
          </div>
        </div>
      </div>
    </li>
  </ul>
</div>

Custom value format

<div class="list">
  <ul>
    <li class="item-content">
      <div class="item-inner">
        <div class="item-title">
          <div class="item-header">Meeting starts in</div>
          <span id="meeting-start-time"></span>
        </div>
        <div class="item-after">
          <div class="stepper stepper-fill stepper-small stepper-raised" id="stepper-time">
            <div class="stepper-button-minus"></div>
            <div class="stepper-button-plus"></div>
          </div>
        </div>
      </div>
    </li>
  </ul>
</div>