Spinner Widget version 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.
Dependencies
- UI Core
- Widget Factory
- Button
- Globalize (external, optional; for use with the
culture
andnumberFormat
options)
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.
- This widget manipulates its element's value programmatically, therefore a native change may not be fired when the element's value changes.
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:
1
|
|
Get or set the culture option, after initialization:
1
2
3
4
5
|
|
disabledType: Boolean
false
true
.Initialize the spinner with the disabled option specified:
1
|
|
Get or set the disabled option, after initialization:
1
2
3
4
5
|
|
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:
1
|
|
Get or set the icons option, after initialization:
1
2
3
4
5
|
|
incrementalType: Boolean or Function( Integer count )
true
- 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.
Initialize the spinner with the incremental option specified:
1 |
|
Get or set the incremental option, after initialization:
1 2 3 4 5 |
|
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
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.
Initialize the spinner with the max option specified:
1 |
|
Get or set the max option, after initialization:
1 2 3 4 5 |
|
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
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.
Initialize the spinner with the min option specified:
1 |
|
Get or set the min option, after initialization:
1 2 3 4 5 |
|
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:
1
|
|
Get or set the numberFormat option, after initialization:
1
2
3
4
5
|
|
pageType: Number
10
Initialize the spinner with the page option specified:
1
|
|
Get or set the page option, after initialization:
1
2
3
4
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
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
.
Initialize the spinner with the step option specified:
1 |
|
Get or set the step option, after initialization:
1 2 3 4 5 |
|
Methods
destroy()
-
This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()
-
This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()
-
This method does not accept any arguments.
Invoke the enable method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
-
This method does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
pageDown( [pages ] )
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:
1
|
|
pageUp( [pages ] )
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:
1
|
|
stepDown( [steps ] )
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:
1
|
|
stepUp( [steps ] )
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:
1
|
|
value()Returns: Number
numberFormat
and culture
options.-
This method does not accept any arguments.
Invoke the method:
1
|
|
value( value )
-
valueThe value to set. If passed as a string, the value is parsed based on the
numberFormat
andculture
options.
Invoke the method:
1
|
|
widget()Returns: jQuery
jQuery
object containing the generated wrapper.-
This method does not accept any arguments.
Invoke the widget method:
1
|
|
Events
change( event, ui )Type: spinchange
Initialize the spinner with the change callback specified:
1
2
3
|
|
Bind an event listener to the spinchange event:
1
|
|
create( event, ui )Type: spincreate
Initialize the spinner with the create callback specified:
1
2
3
|
|
Bind an event listener to the spincreate event:
1
|
|
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:
1
2
3
|
|
Bind an event listener to the spin event:
1
|
|
start( event, ui )Type: spinstart
Initialize the spinner with the start callback specified:
1
2
3
|
|
Bind an event listener to the spinstart event:
1
|
|
stop( event, ui )Type: spinstop
Initialize the spinner with the stop callback specified:
1
2
3
|
|
Bind an event listener to the spinstop event:
1
|
|
Example:
Plain number spinner
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
|