Spinner Widgetversion added: 1.9
Description: Enhance a text input for entering numeric values, with up/down buttons and arrow key handling.
Spinner, or number stepper, widget is perfect for handling all kinds of numeric input. It allow 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, adds two buttons to increment and decrement the current value, along with handling key events for the same purpose. It 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.
Additional Notes:
- 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.
Options
cultureType: String
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.Initialize the spinner with the culture option specified:
$( ".selector" ).spinner({ culture: "fr" }); |
Get or set the culture option, after initialization:
// gettervar culture = $( ".selector" ).spinner( "option", "culture" );// setter$( ".selector" ).spinner( "option", "culture", "fr" ); |
disabledType: Boolean
false
true.Initialize the spinner with the disabled option specified:
$( ".selector" ).spinner({ disabled: true }); |
Get or set the disabled option, after initialization:
// gettervar disabled = $( ".selector" ).spinner( "option", "disabled" );// setter$( ".selector" ).spinner( "option", "disabled", true ); |
iconsType: Object
{ 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")
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:
// gettervar icons = $( ".selector" ).spinner( "option", "icons" );// setter$( ".selector" ).spinner( "option", "icons", { down: "custom-down-icon", up: "custom-up-icon" } ); |
incrementalType: Boolean or Function()
true
-
Boolean: When set to
true, the stepping delta will increase when spun incessantly. When set tofalse, all steps are equal (as defined by thestepoption). - Function: Receives one parameter: the number of spins that have occurred. Must return the number of steps that should occur for the current spin.
Initialize the spinner with the incremental option specified:
$( ".selector" ).spinner({ incremental: false }); |
Get or set the incremental option, after initialization:
// gettervar incremental = $( ".selector" ).spinner( "option", "incremental" );// setter$( ".selector" ).spinner( "option", "incremental", false ); |
maxType: Number or String
null
max attribute is used if it exists and the option is not explicitly set. If null, there is no maximum enforced.- Number: The maximum value.
-
String: If Globalize is included, the
maxoption can be passed as a string which will be parsed based on thenumberFormatandcultureoptions; otherwise it will fall back to the nativeparseFloat()method.
Initialize the spinner with the max option specified:
$( ".selector" ).spinner({ max: 50 }); |
Get or set the max option, after initialization:
// gettervar max = $( ".selector" ).spinner( "option", "max" );// setter$( ".selector" ).spinner( "option", "max", 50 ); |
minType: Number or String
null
min attribute is used if it exists and the option is not explicitly set. If null, there is no minimum enforced.- Number: The minimum value.
-
String: If Globalize is included, the
minoption can be passed as a string which will be parsed based on thenumberFormatandcultureoptions; otherwise it will fall back to the nativeparseFloat()method.
Initialize the spinner with the min option specified:
$( ".selector" ).spinner({ min: 0 }); |
Get or set the min option, after initialization:
// gettervar min = $( ".selector" ).spinner( "option", "min" );// setter$( ".selector" ).spinner( "option", "min", 0 ); |
numberFormatType: String
null
Globalize, if available. Most common are "n" for a decimal number and "C" for a currency value. Also see the culture option.Initialize the spinner with the numberFormat option specified:
$( ".selector" ).spinner({ numberFormat: "n" }); |
Get or set the numberFormat option, after initialization:
// gettervar numberFormat = $( ".selector" ).spinner( "option", "numberFormat" );// setter$( ".selector" ).spinner( "option", "numberFormat", "n" ); |
pageType: Number
10
Initialize the spinner with the page option specified:
$( ".selector" ).spinner({ page: 5 }); |
Get or set the page option, after initialization:
// gettervar page = $( ".selector" ).spinner( "option", "page" );// setter$( ".selector" ).spinner( "option", "page", 5 ); |
stepType: Number or String
1
stepUp()/stepDown() methods. The element's step attribute is used if it exists and the option is not explicitly set.- Number: The size of the step.
-
String: If Globalize is included, the
stepoption can be passed as a string which will be parsed based on thenumberFormatandcultureoptions, otherwise it will fall back to the nativeparseFloat.
Initialize the spinner with the step option specified:
$( ".selector" ).spinner({ step: 2 }); |
Get or set the step option, after initialization:
// gettervar step = $( ".selector" ).spinner( "option", "step" );// setter$( ".selector" ).spinner( "option", "step", 2 ); |
Methods
destroy()
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).spinner( "destroy" ); |
disable()
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).spinner( "disable" ); |
enable()
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).spinner( "enable" ); |
option( optionName )Returns: Object
optionName.-
optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).spinner( "option", "disabled" ); |
option()Returns: PlainObject
- This method does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).spinner( "option" ); |
option( optionName, value )
optionName.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).spinner( "option", "disabled", true ); |
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).spinner( "option", { disabled: true } ); |
pageDown( [pages ] )
page option. Without the parameter, a single page is decremented.
-
pagesType: NumberNumber of pages to decrement, defaults to 1.
Invoke the pageDown method:
$( ".selector" ).spinner( "pageDown" ); |
pageUp( [pages ] )
page option. Without the parameter, a single page is incremented.
-
pagesType: NumberNumber of pages to increment, defaults to 1.
Invoke the pageUp method:
$( ".selector" ).spinner( "pageUp", 10 ); |
stepDown( [steps ] )
If the resulting value is above the max, below the min, or reuslts in a step mismatch, the value will be adjusted to the closest valid value.
-
stepsType: NumberNumber of steps to decrement, defaults to 1.
Invoke the stepDown method:
$( ".selector" ).spinner( "stepDown" ); |
stepUp( [steps ] )
If the resulting value is above the max, below the min, or reuslts in a step mismatch, the value will be adjusted to the closest valid value.
-
stepsType: NumberNumber of steps to increment, defaults to 1.
Invoke the stepUp method:
$( ".selector" ).spinner( "stepUp", 5 ); |
value()Returns: Number
numberFormat and culture options.- This method does not accept any arguments.
Invoke the method:
var value = $( ".selector" ).spinner( "value" ); |
value( value )
-
valueThe value to set. If passed as a string, the value is parsed based on the
numberFormatandcultureoptions.
Invoke the method:
$( ".selector" ).spinner( "value", 50 ); |
widget()Returns: jQuery
jQuery object containing the generated wrapper.
- This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).spinner( "widget" ); |
Events
change( event, ui )Type: spinchange
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 ) {} ); |
create( event, ui )Type: spincreate
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( event, ui )Type: 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 ) {} ); |
start( event, ui )Type: spinstart
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 ) {} ); |
stop( event, ui )Type: spinstop
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 ) {} ); |
Example:
Plain number spinner
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <!doctype html><html lang="en"><head> <meta charset="utf-8"> <title>spinner demo</title></head><body><input id="spinner"><script>$( "#spinner" ).spinner();</script></body></html> |