jQuery UI spinner documentation

## Spinner Widgetversion added: 1.9

Description: Enhance a text input for entering numeric values, with up/down buttons and arrow key handling.

## QuickNavExamples

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

Default: `null`
Sets the culture to use for parsing and formatting the value. If `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"` `);`

### disabledType: Boolean

Default: `false`
Disables the spinner if set to `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` `);`

### iconsType: Object

Default: `{ down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }`
Icons to use for buttons, matching an icon defined by the jQuery UI CSS Framework.

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

### incrementalType: Boolean or Function()

Default: `true`
Controls the number of steps taken when holding down a spin button.
Multiple types supported:

- Boolean: When set to `true`, the stepping delta will increase when spun incessantly. When set to `false`, all steps are equal (as defined by the `step` 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` `);`

### maxType: Number or String

Default: `null`
The maximum allowed value. The element's `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 the `numberFormat` and `culture` options; otherwise it will fall back to the native `parseFloat()` 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 );`

### minType: Number or String

Default: `null`
The minimum allowed value. The element's `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 the `numberFormat` and `culture` options; otherwise it will fall back to the native `parseFloat()` 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 );`

### numberFormatType: String

Default: `null`
Format of numbers passed to `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"` `);`

### pageType: Number

Default: `10`
The number of steps to take when paging via the `pageUp`/`pageDown` methods.
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 );`

### stepType: Number or String

Default: `1`
The 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.
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 the `numberFormat` and `culture` options, otherwise it will fall back to the native `parseFloat`.

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 );`

## Methods

### destroy()

Removes the spinner functionality completely. This will return the element back to its pre-init state.

- This method does not accept any arguments.

Code examples:

Invoke the destroy method:

`$(` `".selector"` `).spinner(` `"destroy"` `);`

### disable()

Disables the spinner.

- This method does not accept any arguments.

Code examples:

Invoke the disable method:

`$(` `".selector"` `).spinner(` `"disable"` `);`

### enable()

Enables the spinner.

- This method does not accept any arguments.

Code examples:

Invoke the enable method:

`$(` `".selector"` `).spinner(` `"enable"` `);`

### option( optionName )Returns: Object

Gets the value currently associated with the specified `optionName`.

- optionName
  Type: String
  The name of the option to get.

Code examples:

Invoke the method:

`var` `isDisabled = $(` `".selector"` `).spinner(` `"option"``,` `"disabled"` `);`

### option()Returns: PlainObject

Gets an object containing key/value pairs representing the current spinner options hash.

- This method does not accept any arguments.

Code examples:

Invoke the method:

`var` `options = $(` `".selector"` `).spinner(` `"option"` `);`

### option( optionName, value )

Sets the value of the spinner option associated with the specified `optionName`.

- optionName
  Type: String
  The name of the option to set.
- value
  Type: Object
  A value to set for the option.

Code examples:

Invoke the method:

`$(` `".selector"` `).spinner(` `"option"``,` `"disabled"``,` `true` `);`

### option( options )

Sets one or more options for the spinner.

- options
  Type: Object
  A map of option-value pairs to set.

Code examples:

Invoke the method:

`$(` `".selector"` `).spinner(` `"option"``, { disabled:` `true` `} );`

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

- pages
  Type: Number
  Number of pages to decrement, defaults to 1.

Code examples:

Invoke the pageDown method:

`$(` `".selector"` `).spinner(` `"pageDown"` `);`

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

- pages
  Type: Number
  Number of pages to increment, defaults to 1.

Code examples:

Invoke the pageUp method:

`$(` `".selector"` `).spinner(` `"pageUp"``, 10 );`

### 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 reuslts in a step mismatch, the value will be adjusted to the closest valid value.

- steps
  Type: Number
  Number of steps to decrement, defaults to 1.

Code examples:

Invoke the stepDown method:

`$(` `".selector"` `).spinner(` `"stepDown"` `);`

### 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 reuslts in a step mismatch, the value will be adjusted to the closest valid value.

- steps
  Type: Number
  Number of steps to increment, defaults to 1.

Code examples:

Invoke the stepUp method:

`$(` `".selector"` `).spinner(` `"stepUp"``, 5 );`

### value()Returns: Number

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.

Code examples:

Invoke the method:

`var` `value = $(` `".selector"` `).spinner(` `"value"` `);`

### value( value )

- value
  Type: Number or String
  The value to set. If passed as a string, the value is parsed based on the `numberFormat` and `culture` options.

Code examples:

Invoke the method:

`$(` `".selector"` `).spinner(` `"value"``, 50 );`

### widget()Returns: jQuery

Returns a `jQuery` object containing the generated wrapper.

- This method does not accept any arguments.

Code examples:

Invoke the widget method:

`var` `widget = $(` `".selector"` `).spinner(` `"widget"` `);`

## Events

### change( event, ui )Type: `spinchange`

Triggered when the value of the spinner has changed and the input is no longer focused.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered when the spinner is created.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered during increment/decrement (to determine direction of spin compare current value with `ui.value`).

Can be canceled, preventing the value from being updated.

- event
  Type: Event
- ui
  Type: Object
  - value
    Type: Number
    The new value to be set, unless the event is cancelled.

Code examples:

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`

Triggered before a spin. Can be canceled, preventing the spin from occurring.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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`

Triggered after a spin.

- event
  Type: Event
- ui
  Type: Object

Code examples:

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``>`
`` `<``link` `rel``=``"stylesheet"` `href``=``"http://code.jquery.com/ui/1.9.2/themes/base/jquery-ui.css"``>`
`` `<``script` `src``=``"http://code.jquery.com/jquery-1.8.3.js"``></``script``>`
`` `<``script` `src``=``"http://code.jquery.com/ui/1.9.2/jquery-ui.js"``></``script``>`
`</``head``>`
`<``body``>`
`<``input` `id``=``"spinner"``>`
`<``script``>`
`$( "#spinner" ).spinner();`
`</``script``>`
`</``body``>`
`</``html``>`

#### Demo: