A spin box widget in JavaScript

A spin box or spinner is a user interface widget consisting of a numeric entry field combined with buttons to increment and decrement the displayed value. SpinBox is a JavaScript object that converts text input fields into spin boxes. The value can be changed using the spinner buttons or by typing, using the up and down arrow keys, or using the mouse wheel when the field has the focus. The examples below show the various types of spin boxes that can be created.

Download SpinBox

Download one of the files below and either incorporate it into your code or serve it as a separate file.

SpinBox does not apply any styling to the spin boxes. The archives below contain a stylesheet and images that give spin boxes the same appearance as those in the examples above.

Creating spin boxes

The spin box is created within an HTML element. The element can either be empty, or contain a text input field — for example:

1
2
3

<span id="container">
  <input type="text" name="number" value="0">
</span>

By putting a text input field within the containing element the user will be able to enter a value even if JavaScript is not available. This fallback functionality is important if the spin box is used to enhance a normal web page, but is not required inside a full JavaScript application.

To convert a text input field into a spin box, a new instance of SpinBox should be created. Either the ID of the containing element, or the DOM node corresponding to it, should be passed as a parameter. For example:

1
2
3
4
5

// create a spin box by passing an ID
var spinbox1 = new SpinBox('spinbox1');

// create a spin box by passing a DOM node
var spinbox2 = new SpinBox(document.getElementById('spinbox2'));

Spin box options

The SpinBox constructor can take a second parameter consisting of an object setting various options. As many or as few options as required can be specified.

By default SpinBox.js sets a class of spinBox on the container, and classes of spinnerUp and spinnerDown on the buttons. The className option sets an alternative class to use on the container, and with suffixes of Up and Down on the buttons:

1
2

// create a spin box with a custom class
var spinbox = new SpinBox('spinbox', {'className' : 'customSpinBox'});

If the container was empty before the spin box was created, the new input field will default to a value of zero. The value option sets the initial value for the input field (regardless of whether the container was empty):

1
2

// create a spin box with an initial value of 10
var spinbox = new SpinBox('spinbox', {'value' : 10});

The spinner buttons will increase or decrease the value by 1 by default. The step option sets an alternative step size:

1
2

// create a spin box that increase and decreases in multiples of 10
var spinbox = new SpinBox('spinbox', {'step' : 10});

There are no limits on the value by default. The minimum and maximum options can be used to restrict the value:

1
2
3
4
5
6
7
8

// create a spin box with a minimum of 1
var spinbox1 = new SpinBox('spinbox1', {'minimum' : 1});

// create a spin box with a maximum of 99
var spinbox2 = new SpinBox('spinbox2', {'maximum' : 99});

// create a spin box with a range of 0 to 100
var spinbox3 = new SpinBox('spinbox3', {'minimum' : 0, 'maximum' : 100});

The spin box only allows whole numbers by default. To override this behaviour, use the decimals option to set the number of decimal places displayed:

1
2

// create a spin box with two decimal places
var spinbox = new SpinBox('spinbox', {'decimals' : 2});

Note that the minimum, maximum, and decimal places restrictions are enforced for values set by the spin box, but a value outside of these restrictions may be typed by the user.

Getting and setting values

The getValue function provides access to the current value:

1
2

// store the current value
var value = spinbox.getValue();

This will be a number, or the value NaN if the current contents of the input field do not start with a valid number. Use the isNaN function to distinguish between the two cases.

The setValue function sets the value, while enforcing any minimum, maximum, and decimal places restrictions:

1
2

// set the value to 10
spinbox.setValue(10);

Where now?

• Home
• PHP
• JavaScript
• HTML and CSS
• Lambda calculus
• Articles
• Follow me on twitter