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.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.

Syntax

The spinner() method can be used in two forms −

$ (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.

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" }
);
2 disabled

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 }
);
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" }.

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" } }
);
4 incremental

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.

  • Function − This must return the number of steps that should occur for the current spin.

Syntax

$( ".selector" ).spinner(
   { incremental: false }
);
5 max

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.

  • 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 }
);
6 min

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.

  • 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 }
);
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.

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" }
);
8 page

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 }
);
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.

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.

  • 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.

Default 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 −

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>
<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.

Use of icons Option

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.

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>
<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 −

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.

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");
2 disable

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");
3 enable

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");
4 option( optionName )

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" );
5 option

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" );
6 option( optionName, value )

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 );
7 option( options )

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 });
8 pageDown( [pages ] )

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");
9 pageUp( [pages ] )

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");
10 stepDown( [steps ] )

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");
11 stepUp( [steps ] )

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");
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.

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" );
13 value( 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 );
14 widget

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.

Use of action stepUp, stepDown, pageUp, and pageDown

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.

Use of action enable, and disable

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.

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.

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 ) {}
});
2 create(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 ) {}
});
3 spin(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.

and represents the new value to be set, unless the event is cancelled.

Syntax

$( ".selector" ).spinner({
   spin: function( event, ui ) {}
});
4 start(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 ) {}
});
5 stop(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 ) {}
});

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>
<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.

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.

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 "" +
    "" +
    "";
}
2 _uiSpinnerHtml(event)

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 "";
}
The jQuery UI Widget Factory is an extensible base on which all of jQuery UI's widgets are built. Using the widget factory to build a plugin provides conveniences for state management, as well as conventions for common tasks like exposing plugin methods and changing options after instantiation.
Advertisements