The Spinner, or number stepper widget, is perfect for handling all kinds of numeric input. It allows users to type a value directly, or modify an existing value by spinning with the keyboard, mouse or scrollwheel. When combined with Globalize, you can even spin currencies and dates in a variety of locales.
Spinner wraps a text input with two buttons to increment and decrement the current value. Key events are added so that the same incrementing and decrementing can be done with the keyboard. Spinner delegates to Globalize for number formatting and parsing.
Keyboard interaction
-
UP
: Increment the value by one step. -
DOWN
: Decrement the value by one step. -
PAGE UP
: Increment the value by one page. -
PAGE DOWN
: Decrement the value by one page.
Focus stays in the text field, even after using the mouse to click one of the spin buttons.
When the spinner is not read only (<input readonly>
), the user may enter text that causes an invalid value (below min, above max, step mismatch, non-numeric input). Whenever a step is taken, either programmatically or via the step buttons, the value will be forced to a valid value (see the description for stepUp()
and stepDown()
for more details).
Theming
The spinner widget uses the jQuery UI CSS framework to style its look and feel. If spinner specific styling is needed, the following CSS class names can be used:
-
ui-spinner
: The outer container of the spinner.-
ui-spinner-input
: The<input>
element that the Spinner widget was instantiated with. -
ui-spinner-button
: The button controls used to increment and decrement the spinner's value. The up button will additionally have aui-spinner-up
class and the down button will additionally have aui-spinner-down
class.
-
Dependencies
- UI Core
- Widget Factory
- Button
- Globalize (external, optional; for use with the
culture
andnumberFormat
options)
- This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.
- This widget manipulates its element's value programmatically, therefore a native
change
event may not be fired when the element's value changes. - Creating a spinner on an
<input type="number">
is not supported due to a UI conflict with the native spinner.
null
null
, the currently set culture in Globalize
is used, see Globalize docs for available cultures. Only relevant if the numberFormat
option is set. Requires Globalize to be included.Code examples:
Initialize the spinner with the culture
option specified:
$( ".selector" ).spinner({ culture: "fr" });
Get or set the culture
option, after initialization:
// Getter var culture = $( ".selector" ).spinner( "option", "culture" ); // Setter $( ".selector" ).spinner( "option", "culture", "fr" );
false
true
.Code examples:
Initialize the spinner with the disabled
option specified:
$( ".selector" ).spinner({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).spinner( "option", "disabled" ); // Setter $( ".selector" ).spinner( "option", "disabled", true );
{ down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }
- up (string, default: "ui-icon-triangle-1-n")
- down (string, default: "ui-icon-triangle-1-s")
Code examples:
Initialize the spinner with the icons
option specified:
$( ".selector" ).spinner({ icons: { down: "custom-down-icon", up: "custom-up-icon" } });
Get or set the icons
option, after initialization:
// Getter var icons = $( ".selector" ).spinner( "option", "icons" ); // Setter $( ".selector" ).spinner( "option", "icons", { down: "custom-down-icon", up: "custom-up-icon" } );
true
Multiple types supported:
- Boolean: When set to
true
, the stepping delta will increase when spun incessantly. When set tofalse
, all steps are equal (as defined by thestep
option). - Function: Receives one parameter: the number of spins that have occurred. Must return the number of steps that should occur for the current spin.
Code examples:
Initialize the spinner with the incremental
option specified:
$( ".selector" ).spinner({ incremental: false });
Get or set the incremental
option, after initialization:
// Getter var incremental = $( ".selector" ).spinner( "option", "incremental" ); // Setter $( ".selector" ).spinner( "option", "incremental", false );
null
max
attribute is used if it exists and the option is not explicitly set. If null
, there is no maximum enforced.Multiple types supported:
- Number: The maximum value.
- String: If Globalize is included, the
max
option can be passed as a string which will be parsed based on thenumberFormat
andculture
options; otherwise it will fall back to the nativeparseFloat()
method.
Code examples:
Initialize the spinner with the max
option specified:
$( ".selector" ).spinner({ max: 50 });
Get or set the max
option, after initialization:
// Getter var max = $( ".selector" ).spinner( "option", "max" ); // Setter $( ".selector" ).spinner( "option", "max", 50 );
null
min
attribute is used if it exists and the option is not explicitly set. If null
, there is no minimum enforced.Multiple types supported:
- Number: The minimum value.
- String: If Globalize is included, the
min
option can be passed as a string which will be parsed based on thenumberFormat
andculture
options; otherwise it will fall back to the nativeparseFloat()
method.
Code examples:
Initialize the spinner with the min
option specified:
$( ".selector" ).spinner({ min: 0 });
Get or set the min
option, after initialization:
// Getter var min = $( ".selector" ).spinner( "option", "min" ); // Setter $( ".selector" ).spinner( "option", "min", 0 );
null
Globalize
, if available. Most common are "n"
for a decimal number and "C"
for a currency value. Also see the culture
option.Code examples:
Initialize the spinner with the numberFormat
option specified:
$( ".selector" ).spinner({ numberFormat: "n" });
Get or set the numberFormat
option, after initialization:
// Getter var numberFormat = $( ".selector" ).spinner( "option", "numberFormat" ); // Setter $( ".selector" ).spinner( "option", "numberFormat", "n" );
10
Code examples:
Initialize the spinner with the page
option specified:
$( ".selector" ).spinner({ page: 5 });
Get or set the page
option, after initialization:
// Getter var page = $( ".selector" ).spinner( "option", "page" ); // Setter $( ".selector" ).spinner( "option", "page", 5 );
1
stepUp()
/stepDown()
methods. The element's step
attribute is used if it exists and the option is not explicitly set.Multiple types supported:
- Number: The size of the step.
- String: If Globalize is included, the
step
option can be passed as a string which will be parsed based on thenumberFormat
andculture
options, otherwise it will fall back to the nativeparseFloat
.
Code examples:
Initialize the spinner with the step
option specified:
$( ".selector" ).spinner({ step: 2 });
Get or set the step
option, after initialization:
// Getter var step = $( ".selector" ).spinner( "option", "step" ); // Setter $( ".selector" ).spinner( "option", "step", 2 );
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).spinner( "destroy" );
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).spinner( "disable" );
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).spinner( "enable" );
Retrieves the spinner's instance object. If the element does not have an associated instance, undefined
is returned.
Unlike other widget methods, instance()
is safe to call on any element after the spinner plugin has loaded.
- This method does not accept any arguments.
Invoke the instance method:
$( ".selector" ).spinner( "instance" );
- This method does not accept any arguments.
Invoke the isValid method:
var isValid = $( ".selector" ).spinner( "isValid" );
Gets the value currently associated with the specified optionName
.
Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar"
would get the value of the bar
property on the foo
option.
- optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).spinner( "option", "disabled" );
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).spinner( "option" );
Sets the value of the spinner option associated with the specified optionName
.
Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName
. For example, "foo.bar"
would update only the bar
property of the foo
option.
- optionNameType: StringThe name of the option to set.
- valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).spinner( "option", "disabled", true );
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).spinner( "option", { disabled: true } );
Decrements the value by the specified number of pages, as defined by the page
option. Without the parameter, a single page is decremented.
If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.
Invoking pageDown()
will cause start
, spin
, and stop
events to be triggered.
- pagesType: NumberNumber of pages to decrement, defaults to 1.
Invoke the pageDown method:
$( ".selector" ).spinner( "pageDown" );
Increments the value by the specified number of pages, as defined by the page
option. Without the parameter, a single page is incremented.
If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.
Invoking pageUp()
will cause start
, spin
, and stop
events to be triggered.
- pagesType: NumberNumber of pages to increment, defaults to 1.
Invoke the pageUp method:
$( ".selector" ).spinner( "pageUp", 10 );
Decrements the value by the specified number of steps. Without the parameter, a single step is decremented.
If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.
Invoking stepDown()
will cause start
, spin
, and stop
events to be triggered.
- stepsType: NumberNumber of steps to decrement, defaults to 1.
Invoke the stepDown method:
$( ".selector" ).spinner( "stepDown" );
Increments the value by the specified number of steps. Without the parameter, a single step is incremented.
If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.
Invoking stepUp()
will cause start
, spin
, and stop
events to be triggered.
- stepsType: NumberNumber of steps to increment, defaults to 1.
Invoke the stepUp method:
$( ".selector" ).spinner( "stepUp", 5 );
numberFormat
and culture
options.- This signature does not accept any arguments.
Invoke the method:
var value = $( ".selector" ).spinner( "value" );
- valueThe value to set. If passed as a string, the value is parsed based on the
numberFormat
andculture
options.
Invoke the method:
$( ".selector" ).spinner( "value", 50 );
jQuery
object containing the generated wrapper. - This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).spinner( "widget" );
ui-spinner-button
class name for the associated events to work. - This method does not accept any arguments.
Use <button>
elements for the increment and decrement buttons.
_buttonHtml: function() { return "" + "<button class='ui-spinner-button ui-spinner-up'>" + "<span class='ui-icon " + this.options.icons.up + "'>▲</span>" + "</button>" + "<button class='ui-spinner-button ui-spinner-down'>" + "<span class='ui-icon " + this.options.icons.down + "'>▼</span>" + "</button>"; }
<input>
element. - This method does not accept any arguments.
Wrap the spinner with a <div>
with no rounded corners.
_uiSpinnerHtml: function() { return "<div class='ui-spinner ui-widget ui-widget-content'></div>"; }
spinchange
Note: The ui
object is empty but included for consistency with other events.
Initialize the spinner with the change callback specified:
$( ".selector" ).spinner({ change: function( event, ui ) {} });
Bind an event listener to the spinchange event:
$( ".selector" ).on( "spinchange", function( event, ui ) {} );
spincreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the spinner with the create callback specified:
$( ".selector" ).spinner({ create: function( event, ui ) {} });
Bind an event listener to the spincreate event:
$( ".selector" ).on( "spincreate", function( event, ui ) {} );
spin
ui.value
). Can be canceled, preventing the value from being updated.
- eventType: Event
- uiType: Object
- valueType: NumberThe new value to be set, unless the event is cancelled.
-
Initialize the spinner with the spin callback specified:
$( ".selector" ).spinner({ spin: function( event, ui ) {} });
Bind an event listener to the spin event:
$( ".selector" ).on( "spin", function( event, ui ) {} );
spinstart
Note: The ui
object is empty but included for consistency with other events.
Initialize the spinner with the start callback specified:
$( ".selector" ).spinner({ start: function( event, ui ) {} });
Bind an event listener to the spinstart event:
$( ".selector" ).on( "spinstart", function( event, ui ) {} );
spinstop
Note: The ui
object is empty but included for consistency with other events.
Initialize the spinner with the stop callback specified:
$( ".selector" ).spinner({ stop: function( event, ui ) {} });
Bind an event listener to the spinstop event:
$( ".selector" ).on( "spinstop", function( event, ui ) {} );
Plain number spinner
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>spinner demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <script src="//code.jquery.com/jquery-1.10.2.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script> </head> <body> <input id="spinner"> <script> $( "#spinner" ).spinner(); </script> </body> </html>
Please login to continue.