Skip Navigation

Number Selector

A Number Selector allows the user to add or remove quantities incrementally.

Available in React
v2 to v3 Migration Information

Standard Number Selector


When to Use

  • Use a Number Selector when users are most likely to increase or decrease a value by a small range of increments. For example, when adding passengers to a travel booking.

When Not to Use

Examples

Usage

  • In general, the Number Selector input width should be wide enough to comfortably fit the label, but not so wide as to render the Number Selector’s increase/decrease controls too far from the value.
  • The Number Selector should have a default value.

Examples

Number Selector with Hidden Label

This example of the Number Selector may be used when the Number Selector is part of a repetitive grouping, such as a column in a table.


Number Selector Error States

Value must be greater than 0
Please complete the required field


Developer Notes

A Number Selector is a simple combination of two buttons and a number <input> element. The button to decrement the number should have a class of spark-number-selector__down. Similarly, the button to increment the number should have a class of spark-number-selector__up. The Number Selector allows you to provide additional parameters using the following attributes on the input element: min, max, value, and step. If providing these, it is important to verify that the values initially provided for min, max, and value are multiples of the step value.

Use of the Number Selector requires a JavaScript helper. It can be instantiated using new Spark.NumberSelector(el). It implements the Messaging and Validation mixins, and provides mechanisms for getting and setting the value.

The following options may be passed when using new Spark.NumberSelector(el, {});:

Name Type Default Description
validate function null A function to run to validate the state of the input. It should call onValidate with the parameters outlined below.
onValidate function null A callback function run after validation has completed. Callback arguments are isValid, newValue, instance.
onChange function null A callback function run when the input value changes. Callback arguments are newValue, instance.
onFocus function null A callback function run when the input gains focus. Callback arguments are newValue, instance.
onBlur function null A callback function run when the input loses focus. Callback arguments are newValue, instance.

For all available methods and full API, refer to the component code on Bitbucket.

Standard Number Selector

<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector">
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="example-number-selector" min="0" max="22" step="2" aria-live="assertive" aria-describedby="example-number-selector__message"/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector"></button>
        <label for="example-number-selector">
          <span>Label</span>
        </label>
      </div>
      <span id="example-number-selector__message" class="spark-input__message" role="alert"></span>
    </div>

  </div>
</div>

<div class="row">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector">
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="example-number-selector--disabled" min="0" max="22" step="2" aria-live="assertive" aria-describedby="example-number-selector__message" disabled/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector" disabled></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector" disabled></button>
        <label for="example-number-selector--disabled">
          <span>Label</span>
        </label>
      </div>
      <span id="example-number-selector__message" class="spark-input__message" role="alert"></span>
    </div>

  </div>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(el);

Number Selector with Hidden Label

<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector spark-number-selector--hidden-label">
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="example-number-selector--hidden-label" min="0" max="22" step="0.5" aria-live="assertive" aria-describedby="example-number-selector__message--hidden-label" />
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector--hidden-label"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector--hidden-label"></button>
        <label for="example-number-selector--hidden-label">
          <span class="spark-assistive-text">Label</span>
        </label>
      </div>
      <span id="example-number-selector__message--hidden-label" class="spark-input__message" role="alert"></span>
    </div>

  </div>
</div>

<div class="row">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector spark-number-selector--hidden-label">
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="example-number-selector--hidden-label--disabled" min="0" max="22" step="0.5" aria-live="assertive" aria-describedby="example-number-selector__message--hidden-label--disabled" disabled />
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector--hidden-label--disabled" disabled></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector--hidden-label--disabled" disabled></button>
        <label for="example-number-selector--hidden-label--disabled">
          <span class="spark-assistive-text">Label</span>
        </label>
      </div>
      <span id="example-number-selector__message--hidden-label--disabled" class="spark-input__message" role="alert"></span>
    </div>

  </div>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(el);

Number Selector Error States

Value must be greater than 0
Please complete the required field 
<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector" data-error>
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="number-selector-example--error" min="0" max="22" step="1" aria-invalid="true" aria-live="assertive" aria-describedby="example-message--error"/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="number-selector-example--error"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="number-selector-example--error"></button>
        <label for="number-selector-example--error">
          <span>Label</span>
        </label>
      </div>
      <span id="example-message--error" class="spark-input__message" role="alert">Value must be greater than 0</span>
    </div>

  </div>
</div>

<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector spark-number-selector--hidden-label" data-error>
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="number-selector-example2--error" min="0" max="22" step="1" aria-live="assertive" aria-describedby="example-message2--error"/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="number-selector-example2--error"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="number-selector-example2--error"></button>
        <label for="number-selector-example2--error">
          <span class="spark-assistive-text">Label</span>
        </label>
      </div>
      <span id="example-message2--error" class="spark-input__message" role="alert">Please complete the required field</span>
    </div>
    
  </div>
</div>


<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(numberSelectors[i], {
  onChange: function(value, inst) {
    var input = document.querySelector('#' + inst.inputEl.id);
    var messageID = document.querySelector('.spark-input__message').getAttribute('id');

    if (value > 0) {
      inst.clearMessages();
      input.removeAttribute('aria-describedby');
      input.removeAttribute('aria-invalid');
    } else {
      inst.setError();
      input.setAttribute('aria-describedby', messageID);
      input.setAttribute('aria-invalid', true);
    }
  },
  onInput: function(value, inst) {
    var input = document.querySelector('#' + inst.inputEl.id);
    var messageID = document.querySelector('.spark-number-selector__message').getAttribute('id');

    if (value > 0) {
      inst.clearMessages();
      input.removeAttribute('aria-describedby');
      input.removeAttribute('aria-invalid');
    } else {
      inst.setError();
      input.setAttribute('aria-describedby', messageID);
      input.setAttribute('aria-invalid', true);
    }
  }
});

Right-to-Left Support

 
<bdo dir="rtl">
  <div class="row spark-mar-b-2">
    <div class="col-xs-10 col-sm-9 col-lg-5">

      <div class="spark-number-selector">
        <div class="spark-number-selector__item">
          <input type="number" value="0" id="example-number-selector" min="0" max="22" step="2" aria-live="assertive" aria-describedby="example-number-selector__message" />
          <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector"></button>
          <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector"></button>
          <label for="example-number-selector">
            <span>תווית</span>
          </label>
        </div>
        <span id="example-number-selector__message" class="spark-input__message" role="alert"></span>
      </div>

    </div>
  </div>

  <div class="row">
    <div class="col-xs-10 col-sm-9 col-lg-5">

      <div class="spark-number-selector">
        <div class="spark-number-selector__item">
          <input type="number" value="0" id="example-number-selector--disabled" min="0" max="22" step="2" aria-live="assertive" aria-describedby="example-number-selector__message--disabled" disabled />
          <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="example-number-selector--disabled" disabled></button>
          <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="example-number-selector--disabled" disabled></button>
          <label for="example-number-selector--disabled">
            <span>תווית</span>
          </label>
        </div>
        <span id="example-number-selector__message--disabled" class="spark-input__message" role="alert"></span>
      </div>

    </div>
  </div>
</bdo>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(el);

Accessibility Notes

The Number Selector component requires additional steps when included within a product to make it fully accessible to assistive technologies. This is to be done at the product level as the context and language requirements will vary between different products, and as such this functionality is not included within the Spark library.

The label element requires a for attribute that identifies which element it is bound to, in this case the input element. The id of the input should match the for attribute of the label.

Each of the buttons in the selector has an aria-label attribute to provide alternative text as the visible portion of the buttons simply show a ‘+’ or ‘-‘. The buttons also have aria-controls attributes to indicate which element they control. The value of these attributes is the id of the input element.

The input also has additional ARIA attributes, some of which can change based on the current status of the component. The aria-live attribute which has been set to ‘assertive’ to provide immediate feedback as the value of the input is changed using the button controls or the value is manually typed into the field. Along with aria-invalid, the aria-describedby attribute indicates which element will provide additional context for the field when there is an error. In this example, this attribute is added or removed using Javascript depending on whether there is an error or not. The value of the aria-describedby attribute is the same value as the id of the element that holds the error message that gets displayed. The role attribute is applied to the error message element and is used to announce the message as it’s displayed. Refer to the JS tab below to see an example of how this functionality could be included.

Error States

Value must be greater than 0
Please complete the required field 
<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector" data-error>
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="number-selector-example--error" min="0" max="22" step="1" aria-invalid="true" aria-live="assertive" aria-describedby="example-message--error"/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="number-selector-example--error"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="number-selector-example--error"></button>
        <label for="number-selector-example--error">
          <span>Label</span>
        </label>
      </div>
      <span id="example-message--error" class="spark-input__message" role="alert">Value must be greater than 0</span>
    </div>

  </div>
</div>

<div class="row spark-mar-b-2">
  <div class="col-xs-10 col-sm-9 col-lg-5">

    <div class="spark-number-selector spark-number-selector--hidden-label" data-error>
      <div class="spark-number-selector__item">
        <input type="number" value="0" id="number-selector-example2--error" min="0" max="22" step="1" aria-live="assertive" aria-describedby="example-message2--error"/>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-subtract spark-number-selector__down" aria-label="Less" aria-controls="number-selector-example2--error"></button>
        <button class="spark-btn spark-icon spark-btn--secondary spark-icon-math-add spark-number-selector__up" aria-label="More" aria-controls="number-selector-example2--error"></button>
        <label for="number-selector-example2--error">
          <span class="spark-assistive-text">Label</span>
        </label>
      </div>
      <span id="example-message2--error" class="spark-input__message" role="alert">Please complete the required field</span>
    </div>
    
  </div>
</div>


<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(numberSelectors[i], {
  onChange: function(value, inst) {
    var input = document.querySelector('#' + inst.inputEl.id);
    var messageID = document.querySelector('.spark-input__message').getAttribute('id');

    if (value > 0) {
      inst.clearMessages();
      input.removeAttribute('aria-describedby');
      input.removeAttribute('aria-invalid');
    } else {
      inst.setError();
      input.setAttribute('aria-describedby', messageID);
      input.setAttribute('aria-invalid', true);
    }
  },
  onInput: function(value, inst) {
    var input = document.querySelector('#' + inst.inputEl.id);
    var messageID = document.querySelector('.spark-number-selector__message').getAttribute('id');

    if (value > 0) {
      inst.clearMessages();
      input.removeAttribute('aria-describedby');
      input.removeAttribute('aria-invalid');
    } else {
      inst.setError();
      input.setAttribute('aria-describedby', messageID);
      input.setAttribute('aria-invalid', true);
    }
  }
});