JqueryUI - Spinner, JqueryUI,
Spinner widget adds a up/down arrow to the left of a input box thus allowing a user to increment/decrement a value in the input box. It allows users to type a value directly, or modify an existing value by spinning with the keyboard, mouse or scrollwheel. It also has a step feature to skip values. In addition to the basic numeric features, it also enables globalized formatting options (ie currency, thousand separator, decimals, etc.) thus providing a convenient internationalized masked entry box.The following example depends on Globalize. You can get the Globalize files from https://github.com/jquery/globalize. Click the releases link, select the version you want, and download the .zip or tar.gz file. Extract the files and copy the following files to the folder where your example is located.jQueryUI provides spinner() method which creates a spinner.
These files are also present in the external folder of your jquery-ui library.
- lib/globalize.js : This file contains the Javascript code for dealing with localizations
- lib/globalize.culture.js : This file contains a complete set of the locales that the Globalize library comes with.
Syntax
The spinner() method can be used in two forms −- $(selector, context).spinner (options) Method
- $(selector, context).spinner ("action", params) Method
$ (selector, context).spinner (options) Method
The spinner (options) method declares that an HTML element and its contents should be treated and managed as spinner. The options parameter is an object that specifies the appearance and behavior of the spinner elements involved.Syntax
$(selector, context).spinner (options);You can provide one or more options at a time using Javascript object. If there are more than one options to be provided then you will separate them using a comma as follows −
$(selector, context).spinner({option1: value1, option2: value2..... });The following table lists the different options that can be used with this method −
| Sr.No. | Option & Description |
|---|---|
| 1 | culture This option sets the culture to use for parsing and formatting the value. By default its value is null which means the currently set culture in Globalize is used. |
| 2 | disabled This option if set to true disables spinner. By default its value is false. |
| 3 | icons This option sets icons to use for buttons, matching an icon provided by the jQuery UI CSS Framework. By default its value is { down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }. |
| 4 | incremental This option controls the number of steps taken when holding down a spin button. By default its value is true. |
| 5 | max This option indicates the maximum allowed value. By default its value is null which means there is no maximum enforced. |
| 6 | min This option indicates the minimum allowed value. By default its value is null which means there is no minimum enforced. |
| 7 | numberFormat This option indicates format of numbers passed to Globalize, if available. Most common are "n" for a decimal number and "C" for a currency value. By default its value is null. |
| 8 | page This option indicates the number of steps to take when paging via the pageUp/pageDown methods. By default its value is 10. |
| 9 | step This option indicates size of the step to take when spinning via buttons or via the stepUp()/stepDown() methods. The element's step attribute is used if it exists and the option is not explicitly set. |
Default Functionality
The following example demonstrates a simple example of spinner widget functionality, passing no parameters to the spinner() method.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-1 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$( "#spinner-1" ).spinner();
});
</script>
</head>
<body>
<!-- HTML -->
<div id = "example">
<input type = "text" id = "spinner-1" value = "0" />
</div>
</body>
</html>
Use of Min, Max and Step Options
The following example demonstrates the usage of three options min, max and step in the spinner widget of JqueryUI.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-2,#spinner-3 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$( "#spinner-2" ).spinner({
min: -10,
max: 10
});
$('#spinner-3').spinner({
step: 100,
min: -1000000,
max: 1000000
});
});
</script>
</head>
<body>
<!-- HTML -->
<div id = "example">
Spinner Min, Max value set:
<input type = "text" id = "spinner-2" value = "0" /><br><br>
Spinner increments/decrements in step of of 100:
<input type = "text" id = "spinner-3" value = "0" />
</div>
</body>
</html>
In the above example, you can see in the first spinner the max and min values are set to 10 and -10 respectively. Hence crossing these values, the spinner will stop incrementing/decrementing. In the second spinner the spinner value increments/decrements in steps of 100.
Use of icons Option
The following example demonstrates the usage of option icons in the spinner widget of JqueryUI.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-5 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$( "#spinner-5" ).spinner({
icons: {
down: "custom-down-icon", up: "custom-up-icon"
}
});
});
</script>
</head>
<body>
<!-- HTML -->
<div id = "example">
<input type = "text" id = "spinner-5" value = "0" />
</div>
</body>
</html>
In the above example, you can notice the images spinner are changed.
Use of culture, numberFormat, and page options
The following example demonstrates the usage of three options culture, numberFormat and page in the spinner widget of JqueryUI.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output. Now, you can play with the result −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<script src = "/jqueryui/jquery-ui-1.10.4/external/jquery.mousewheel.js"></script>
<script src = "/jqueryui/jquery-ui-1.10.4/external/globalize.js"></script>
<script src = "/jqueryui/jquery-ui-1.10.4/external/globalize.culture.de-DE.js"></script>
<script>
$(function() {
$( "#spinner-4" ).spinner({
culture:"de-DE",
numberFormat:"C",
step:2,
page:10
});
});
</script>
</head>
<body>
<p>
<label for = "spinner-4">Amount to donate:</label>
<input id = "spinner-4" name = "spinner" value = "5">
</p>
</body>
</html>
In the above example, you can see the spinner displays the number in currency format as the numberFormat is set to "C" and culture is set to "de-DE". Here we have used the Globalize files from the jquery-ui library.
$ (selector, context).spinner ("action", params) Method
The spinner ("action", params) method can perform an action on spinner elements, such as enabling/disabling the spinner. The action is specified as a string in the first argument (e.g., "disable" disables the spinner). Check out the actions that can be passed, in the following table.Syntax
$(selector, context).spinner ("action", params);;
The following table lists the different actions that can be used with this method −| Sr.No. | Action & Description |
|---|---|
| 1 | destroy This action destroys the spinner functionality of an element completely. The elements return to their pre-init state. This method does not accept any arguments. |
| 2 | disable This action disables the spinner functionality. This method does not accept any arguments. |
| 3 | enable This action enables the spinner functionality. This method does not accept any arguments. |
| 4 | option( optionName ) This action gets the value currently associated with the specified optionName. Where optionName is the name of the option to get. |
| 5 | option This action gets an object containing key/value pairs representing the current spinner options hash. This method does not accept any arguments. |
| 6 | option( optionName, value ) This action sets the value of the spinner option associated with the specified optionName. |
| 7 | option( options ) This action sets one or more options for the spinner. |
| 8 | pageDown( [pages ] ) This action decrements the value by the specified number of pages, as defined by the page option. |
| 9 | pageUp( [pages ] ) This action increments the value by the specified number of pages, as defined by the page option. |
| 10 | stepDown( [steps ] ) This action decrements the value by the specified number of steps. |
| 11 | stepUp( [steps ] ) This action increments the value by the specified number of steps. |
| 12 | value This action gets the current value as a number. The value is parsed based on the numberFormat and culture options. This method does not accept any arguments. |
| 13 | value( value ) This action sets the value. if value is passed value is parsed based on the numberFormat and culture options. |
| 14 | widget This action returns the spinner widget element; the one annotated with the ui-spinner class name. |
Use of action stepUp, stepDown, pageUp, and pageDown
The following example demonstrates the use of stepUp, stepDown, pageUp and pageDown methods.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you also must see the following output −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-6 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$("#spinner-6").spinner();
$('button').button();
$('#stepUp-2').click(function () {
$("#spinner-6").spinner("stepUp");
});
$('#stepDown-2').click(function () {
$("#spinner-6").spinner("stepDown");
});
$('#pageUp-2').click(function () {
$("#spinner-6").spinner("pageUp");
});
$('#pageDown-2').click(function () {
$("#spinner-6").spinner("pageDown");
});
});
</script>
</head>
<body>
<!-- HTML -->
<input id = "spinner-6" />
<br/>
<button id = "stepUp-2">Increment</button>
<button id = "stepDown-2">Decrement</button>
<button id = "pageUp-2">Increment Page</button>
<button id = "pageDown-2">Decrement Page</button>
</body>
</html>
In the above example, use the respective buttons to increment/decrement the spinner.
Use of action enable, and disable
The following example demonstrates the use of enable and disable methods.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-7 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$("#spinner-7").spinner();
$('button').button();
$('#stepUp-3').click(function () {
$("#spinner-7").spinner("enable");
});
$('#stepDown-3').click(function () {
$("#spinner-7").spinner("disable");
});
});
</script>
</head>
<body>
<!-- HTML -->
<input id = "spinner-7" />
<br/>
<button id = "stepUp-3">Enable</button>
<button id = "stepDown-3">Disable</button>
</body>
</html>
In the above example, use the Enable/Disable buttons to enable or disable the spinner.
Event Management on Spinner Elements
In addition to the spinner (options) method which we saw in the previous sections, JqueryUI provides event methods which gets triggered for a particular event. These event methods are listed below −| Sr.No. | Event Method & Description |
|---|---|
| 1 | change(event, ui) This event is triggered when the value of the spinner has changed and the input is no longer focused. |
| 2 | create(event, ui) This event is triggered when the spinner is created. |
| 3 | spin(event, ui) This event is triggered during increment/decrement. |
| 4 | start(event, ui) This event is triggered before a spin. Can be canceled, preventing the spin from occurring. |
| 5 | stop(event, ui) This event is triggered after a spin. |
Example
The following example demonstrates the event method usage in spinner widgets. This example demonstrates the use of events spin, change and stop.<!doctype html>Let us save the above code in an HTML file spinnerexample.htm and open it in a standard browser which supports javascript, you must also see the following output −
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Spinner functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- CSS -->
<style type = "text/css">
#spinner-8 input {width: 100px}
</style>
<!-- Javascript -->
<script>
$(function() {
$( "#spinner-8" ).spinner({
spin: function( event, ui ) {
var result = $( "#result-2" );
result.append( "Spin Value: "+$( "#spinner-8" ).spinner("value") );
},
change: function( event, ui ) {
var result = $( "#result-2" );
result.append( "Change value: "+$( "#spinner-8" ).spinner("value") );
},
stop: function( event, ui ) {
var result = $( "#result-2" );
result.append( "Stop value: "+$( "#spinner-8" ).spinner("value") );
}
});
});
</script>
</head>
<body>
<!-- HTML -->
<div id = "example">
<input type = "text" id = "spinner-8" value = "0" />
</div>
<span id = "result-2"></span>
</body>
</html>
In the above example change the value of the spinner and see, the messages being displayed below for spin and stop events. Now change the focus of the spinner and you see a message being displayed on change event.
Extension Points
The spinner widget is built with the widget factory and can be extended. To extend widgets, we can either override or add to the behavior of existing methods. Following method provides as extension point with the same API stability as the spinner methods. Listed in the above table.| Sr.No. | Method & Description |
|---|---|
| 1 | _buttonHtml(event) This method return a String which is an HTML. This HTML can be used for the spinner's increment and decrement buttons. Each button must be given a ui-spinner-button class name for the associated events to work. This method does not accept any arguments. |
| 2 | _uiSpinnerHtml(event) This method determine the HTML to use to wrap the spinner's <input> element. This method does not accept any arguments. |