Skip Navigation

Number Selector

A number selector allows the user to add or remove quantities incrementally.


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

Variations

Error State

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) or $(el).sparkNumberSelector(). 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, {}); or $(el).sparkNumberSelector({});:

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.

<div class="spark-number-examples">
  <div class="spark-number-selector">
    <label for="example1">Label</label>
    <button class="spark-btn spark-btn--secondary spark-number-selector__down" aria-label="Less" aria-controls="example1"></button>
    <input id="example1" type="number" min="0" max="3" value="0" step="0.5" role="alert" aria-live="assertive">
    <button class="spark-btn spark-btn--secondary spark-number-selector__up" aria-label="More" aria-controls="example1"></button>
  </div>

  <div class="spark-number-selector">
    <label for="example2">Label</label>
    <button class="spark-btn spark-btn--secondary spark-number-selector__down" aria-label="Less" aria-controls="example2"></button>
    <input id="example2" type="number" min="-10" max="30" value="-5" role="alert" aria-live="assertive">
    <button class="spark-btn spark-btn--secondary spark-number-selector__up" aria-label="More" aria-controls="example2"></button>
  </div>

  <div class="spark-number-selector">
    <label for="example3">Label</label>
    <button class="spark-btn spark-btn--secondary spark-number-selector__down" aria-label="Less" aria-controls="example3"></button>
    <input id="example3" type="number" min="-10" max="30" step="5" value="0" role="alert" aria-live="assertive">
    <button class="spark-btn spark-btn--secondary spark-number-selector__up" aria-label="More" aria-controls="example3"></button>
  </div>

  <div class="spark-number-selector">
    <label for="example4">Label</label>
    <button class="spark-btn spark-btn--secondary spark-number-selector__down" aria-label="Less" disabled aria-controls="example4"></button>
    <input id="example4" type="number" min="-10" max="30" step="5" value="0" disabled role="alert" aria-live="assertive">
    <button class="spark-btn spark-btn--secondary spark-number-selector__up" aria-label="More" disabled aria-controls="example4"></button>
  </div>
</div>

<style type="text/css">
  
.spark-number-examples > .spark-number-selector {
  margin-right: 1rem;
}

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

Error State

Please complete the required field 
<div class="spark-number-selector" data-error>
  <label for="example5">Label</label>
  <button class="spark-btn spark-btn--secondary spark-number-selector__down" aria-label="Less" aria-controls="example5"></button>
  <input id="example5" type="number" min="0" max="3" value="0" role="alert" aria-live="assertive" aria-describedby="error-example">
  <button class="spark-btn spark-btn--secondary spark-number-selector__up" aria-label="More" aria-controls="example5"></button>
  <span id="error-example5" class="spark-number-selector__message">Please complete the required field</span>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-number-selector');
new Spark.NumberSelector(el, {
  onChange: function(value, inst) {
    if(value > 0) {
      inst.setErrorState(false);
    }
    else {
      inst.setErrorState(true);
    }
  },
  onInput: function(value, inst) {
    if(value > 0) {
      inst.setErrorState(false);
    }
    else {
      inst.setErrorState(true);
    }
  }
});

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 role attribute is used to communicate the value of the input as it changes. This has been used in conjunction with 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. 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. Refer to the JS tab below to see an example of how this functionality could be included.

Please complete the required field 
<div class="spark-number-selector" data-error>
  <label for="example5">Label</label>
  <button class="spark-btn spark-btn--secondary spark-number-selector__down" title="Less" aria-controls="example5"></button>
  <input id="example5" type="number" min="0" max="3" value="0" role="alert" aria-live="assertive" aria-describedby="error-example">
  <button class="spark-btn spark-btn--secondary spark-number-selector__up" title="More" aria-controls="example5"></button>
  <span id="error-example" class="spark-number-selector__message">Please complete the required field</span>
</div>
// Vanilla JS
// Customized example to illustrate setting of ARIA attributes

var numberSelectors = document.querySelectorAll('.spark-number-selector');
for(var i = 0, len = numberSelectors.length; i < len; i++) {
  if(numberSelectors[i].hasAttribute('data-error')) {
    new Spark.NumberSelector(numberSelectors[i], {
      onChange: function(value, inst) {
        var input = document.querySelector('#' + inst.inputEl.id);
        var messageID = document.querySelector('.spark-number-selector__message').getAttribute('id');

        if(value > 0) {
          inst.setErrorState(false);
          input.removeAttribute('aria-describedby');
        }
        else {
          inst.setErrorState(true);
          input.setAttribute('aria-describedby', messageID);
        }
      },
      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.setErrorState(false);
          input.removeAttribute('aria-describedby');
        }
        else {
          inst.setErrorState(true);
          input.setAttribute('aria-describedby', messageID);
        }
      }
    });
  }
  else {
    new Spark.NumberSelector(numberSelectors[i]);
  }
}