JqueryUI - Spinner

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.
lib/globalize.js : This file contains the Javascript code for dealing with localizations
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.
lib/globalize.culture.js : This file contains a complete set of the locales that the Globalize library comes with.
These files are also present in the external folder of your jquery-ui library.
jQueryUI provides spinner() method which creates a spinner.
The spinner() method can be used in two forms −
$(selector, context).spinner (options) Method
$(selector, context).spinner (options) Method
$(selector, context).spinner ("action", params) Method
$(selector, context).spinner ("action", params) 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.
$(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 −
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.
Option - 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. Only relevant if the numberFormat option is set. Requires Globalize to be included.
Syntax
$( ".selector" ).spinner(
   { culture: "fr" }
);

This option if set to true disables spinner. By default its value is false.
Option - disabled
This option if set to true disables spinner. By default its value is false.
Syntax
$( ".selector" ).spinner(
   { disabled: true }
);

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" }.
Option - 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" }.
Syntax
$( ".selector" ).spinner(
   { icons: { down: "custom-down-icon", up: "custom-up-icon" } }
);

This option controls the number of steps taken when holding down a spin button. By default its value is true.
Option - incremental
This option controls the number of steps taken when holding down a spin button. By default its value is true.
This can be of type −
Boolean − If set to false all steps are equal. If set to true, the stepping delta will increase when spun incessantly.
Boolean − If set to false all steps are equal. If set to true, the stepping delta will increase when spun incessantly.
Function − This must return the number of steps that should occur for the current spin.
Function − This must return the number of steps that should occur for the current spin.
Syntax
$( ".selector" ).spinner(
   { incremental: false }
);

This option indicates the maximum allowed value. By default its value is null which means there is no maximum enforced.
Option - max
This option indicates the maximum allowed value. By default its value is null which means there is no maximum enforced.
This can be of type −
Number − The maximum value.
Number − The maximum value.
String − If Globalize is included, the max option can be passed as a string which will be parsed based on the numberFormat and culture options
String − If Globalize is included, the max option can be passed as a string which will be parsed based on the numberFormat and culture options
Syntax
$( ".selector" ).spinner(
   { max: 50 }
);

This option indicates the minimum allowed value. By default its value is null which means there is no minimum enforced.
Option - min
This option indicates the minimum allowed value. By default its value is null which means there is no minimum enforced.
This can be of type −
Number − The minimum value.
Number − The minimum value.
String − If Globalize is included, the min option can be passed as a string which will be parsed based on the numberFormat and culture options.
String − If Globalize is included, the min option can be passed as a string which will be parsed based on the numberFormat and culture options
Syntax
$( ".selector" ).spinner(
   { min: 0 }
);

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.
Option - 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.
Syntax
$( ".selector" ).spinner(
   { numberFormat: "n" }
);

This option indicates the number of steps to take when paging via the pageUp/pageDown methods. By default its value is 10.
Option - page
This option indicates the number of steps to take when paging via the pageUp/pageDown methods. By default its value is 10.
Syntax
$( ".selector" ).spinner(
   { page: 5 }
);

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.
Option - 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.
This can be of type −
Number − The size of step.
Number − The size of step.
String − If Globalize is included, the step option can be passed as a string which will be parsed based on the numberFormat and culture options, otherwise it will fall back to the native parseFloat.
String − If Globalize is included, the step option can be passed as a string which will be parsed based on the numberFormat and culture options, otherwise it will fall back to the native parseFloat.
Syntax
$( ".selector" ).spinner(
   { step: 2 }
);

The following section will show you a few working examples of spinner widget functionality.
The following example demonstrates a simple example of spinner widget functionality, passing no parameters to the spinner() method.
<!doctype html>
<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>
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 −
The following example demonstrates the usage of three options min, max and step in the spinner widget of JqueryUI.
<!doctype html>
<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>
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 −
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.
The following example demonstrates the usage of option icons in the spinner widget of JqueryUI.
<!doctype html>
<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>
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 −
In the above example, you can notice the images spinner are changed.
The following example demonstrates the usage of three options culture, numberFormat and page in the spinner widget of JqueryUI.
<!doctype html>
<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>
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 −

Amount to donate:
▲▼

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.
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.
$(selector, context).spinner ("action", params);;

The following table lists the different actions that can be used with this method −
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.
Action - 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.
Syntax
$(".selector").spinner("destroy");

This action disables the spinner functionality. This method does not accept any arguments.
Action - disable
This action disables the spinner functionality. This method does not accept any arguments.
Syntax
$(".selector").spinner("disable");

This action enables the spinner functionality. This method does not accept any arguments.
Action - enable
This action enables the spinner functionality. This method does not accept any arguments.
Syntax
$(".selector").spinner("enable");

This action gets the value currently associated with the specified optionName. Where optionName is the name of the option to get.
Action - option( optionName )
This action gets the value currently associated with the specified optionName. Where optionName is the name of the option to get.
Syntax
var isDisabled = $( ".selector" ).spinner( "option", "disabled" );

This action gets an object containing key/value pairs representing the current spinner options hash. This method does not accept any arguments.
Action - option
This action gets an object containing key/value pairs representing the current spinner options hash. This method does not accept any arguments.
Syntax
var options = $( ".selector" ).spinner( "option" );

This action sets the value of the spinner option associated with the specified optionName.
Action - optionName
This action sets the value of the spinner option associated with the specified optionName.
Syntax
$( ".selector" ).spinner( "option", "disabled", true );

This action sets one or more options for the spinner.
Action - option( options )
This action sets one or more options for the spinner.
Syntax
$(".selector").spinner("option", { disabled: true });

This action decrements the value by the specified number of pages, as defined by the page option.
Action - pageDown( [pages ] )
This action decrements the value by the specified number of pages, as defined by the page option. Invoking pageDown() will cause start, spin, and stop events to be triggered.
Syntax
$(".selector").spinner("pageDown");

This action increments the value by the specified number of pages, as defined by the page option.
Action - pageUp( [pages ] )
This action increments the value by the specified number of pages, as defined by the page option. Invoking pageUp() will cause start, spin, and stop events to be triggered.
Syntax
$(".selector").spinner("pageUp");

This action decrements the value by the specified number of steps.
Action - stepDown( [steps ] )
This action decrements the value by the specified number of steps. Invoking stepDown() will cause start, spin, and stop events to be triggered.
Syntax
$(".selector").spinner("stepDown");

This action increments the value by the specified number of steps.
Action - stepUp( [steps ] )
This action increments the value by the specified number of steps. Invoking stepUp() will cause start, spin, and stop events to be triggered.
Syntax
$(".selector").spinner("stepUp");

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.
Action - 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.
Syntax
var value = $( ".selector" ).spinner( "value" );

This action sets the value. if value is passed value is parsed based on the numberFormat and culture options.
Action - value( value )
This action sets the value. if value is passed value is parsed based on the numberFormat and culture options.
Syntax
$( ".selector" ).spinner( "value", 50 );

This action returns the spinner widget element; the one annotated with the ui-spinner class name.
Action - widget
This action returns the spinner widget element; the one annotated with the ui-spinner class name.
Syntax
$( ".selector" ).spinner( "widget");

The following examples demonstrate how to use the actions given in the above table.
The following example demonstrates the use of stepUp, stepDown, pageUp and pageDown methods.
<!doctype html>
<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>
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 −
In the above example, use the respective buttons to increment/decrement the spinner.
The following example demonstrates the use of enable and disable methods.
<!doctype html>
<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>
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 −
In the above example, use the Enable/Disable buttons to enable or disable the spinner.
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 −
This event is triggered when the value of the spinner has changed and the input is no longer focused.
Event - change(event, ui)
This event is triggered when the value of the spinner has changed and the input is no longer focused. Where event is of type Event, and ui is of type Object.
Syntax
$( ".selector" ).spinner({
   change: function( event, ui ) {}
});

This event is triggered when the spinner is created.
Event - create(event, ui)
This event is triggered when the spinner is created. Where event is of type Event, and ui is of type Object.
Syntax
$( ".selector" ).spinner({
   create: function( event, ui ) {}
});

This event is triggered during increment/decrement.
Event - spin(event, ui)
This event is triggered during increment/decrement. Where event is of type Event, and ui is of type Object.
Syntax
$( ".selector" ).spinner({
   spin: function( event, ui ) {}
});

This event is triggered before a spin. Can be canceled, preventing the spin from occurring.
Event - start(event, ui)
This event is triggered before a spin. Can be canceled, preventing the spin from occurring. Where event is of type Event, and ui is of type Object.
Syntax
$( ".selector" ).spinner({
   start: function( event, ui ) {}
});

This event is triggered after a spin.
Event - stop(event, ui)
This event is triggered after a spin. Where event is of type Event, and ui is of type Object.
Syntax
$( ".selector" ).spinner({
   stop: function( event, ui ) {}
});

The following example demonstrates the event method usage in spinner widgets. This example demonstrates the use of events spin, change and stop.
<!doctype html>
<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>
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 −
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.
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.
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.
Extension Point - _buttonHtml(event, ui)
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.
Code Example
_buttonHtml: function() {
  return "" +
    "" +
      "▲" +
    "" +
    "" +
      "▼" +
    "";
}
This method determine the HTML to use to wrap the spinner's <input> element. This method does not accept any arguments.
Extension Point - _uiSpinnerHtml(event, ui)
This method determine the HTML to use to wrap the spinner's <input> element. This method does not accept any arguments.
Code Example
_uiSpinnerHtml: function() {
  return "";
}
 Print
 Add Notes
 Bookmark this page