## Spinner Widget version 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.

### Dependencies

- UI Core
- Widget Factory
- Button
- Globalize (external, optional; for use with the `culture` and `numberFormat` 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.

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

1

    $( ".selector" ).spinner({ culture: "fr" });

Get or set the `culture` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

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

Get or set the `disabled` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ icons: { down: "custom-down-icon", up: "custom-up-icon" } });

Get or set the `icons` option, after initialization:

1
2
3
4
5

    // gettervar icons = $( ".selector" ).spinner( "option", "icons" ); // setter$( ".selector" ).spinner( "option", "icons", { down: "custom-down-icon", up: "custom-up-icon" } );

### incrementalType: Boolean or Function( Integer count )

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:

1

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

Get or set the `incremental` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ max: 50 });

Get or set the `max` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ min: 0 });

Get or set the `min` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ numberFormat: "n" });

Get or set the `numberFormat` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ page: 5 });

Get or set the `page` option, after initialization:

1
2
3
4
5

    // gettervar 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:

1

    $( ".selector" ).spinner({ step: 2 });

Get or set the `step` option, after initialization:

1
2
3
4
5

    // gettervar step = $( ".selector" ).spinner( "option", "step" ); // setter$( ".selector" ).spinner( "option", "step", 2 );

## Methods

### destroy()Returns: jQuery (plugin only)

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:

1

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

### disable()Returns: jQuery (plugin only)

Disables the spinner.

- This method does not accept any arguments.

Code examples:

Invoke the disable method:

1

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

### enable()Returns: jQuery (plugin only)

Enables the spinner.

- This method does not accept any arguments.

Code examples:

Invoke the enable method:

1

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

1

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

### option()Returns: PlainObject

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

- This signature does not accept any arguments.

Code examples:

Invoke the method:

1

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

### option( optionName, value )Returns: jQuery (plugin only)

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:

1

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

### option( options )Returns: jQuery (plugin only)

Sets one or more options for the spinner.

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

Code examples:

Invoke the method:

1

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

### pageDown( [pages ] )Returns: jQuery (plugin only)

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:

1

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

### pageUp( [pages ] )Returns: jQuery (plugin only)

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:

1

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

### stepDown( [steps ] )Returns: jQuery (plugin only)

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:

1

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

### stepUp( [steps ] )Returns: jQuery (plugin only)

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:

1

    $( ".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 signature does not accept any arguments.

Code examples:

Invoke the method:

1

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

### value( value )Returns: jQuery (plugin only)

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

1

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

1

    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

Note: The `ui` object is empty but included for consistency with other events.

Code examples:

Initialize the spinner with the change callback specified:

1
2
3

    $( ".selector" ).spinner({  change: function( event, ui ) {}});

Bind an event listener to the spinchange event:

1

    $( ".selector" ).on( "spinchange", function( event, ui ) {} );

### create( event, ui )Type: `spincreate`

Triggered when the spinner is created.

- event
  Type: Event
- ui
  Type: Object

Note: The `ui` object is empty but included for consistency with other events.

Code examples:

Initialize the spinner with the create callback specified:

1
2
3

    $( ".selector" ).spinner({  create: function( event, ui ) {}});

Bind an event listener to the spincreate event:

1

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

1
2
3

    $( ".selector" ).spinner({  spin: function( event, ui ) {}});

Bind an event listener to the spin event:

1

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

Note: The `ui` object is empty but included for consistency with other events.

Code examples:

Initialize the spinner with the start callback specified:

1
2
3

    $( ".selector" ).spinner({  start: function( event, ui ) {}});

Bind an event listener to the spinstart event:

1

    $( ".selector" ).on( "spinstart", function( event, ui ) {} );

### stop( event, ui )Type: `spinstop`

Triggered after a spin.

- event
  Type: Event
- ui
  Type: Object

Note: The `ui` object is empty but included for consistency with other events.

Code examples:

Initialize the spinner with the stop callback specified:

1
2
3

    $( ".selector" ).spinner({  stop: function( event, ui ) {}});

Bind an event listener to the spinstop event:

1

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

#### Demo: