Welcome to the Mobiscroll API Reference. You can find the most up to date information about usage and customization options here.
Requires jQuery >= 1.6, Zepto.js >= 1.0rc1 or jqMobi >= 1.0.3
Starting from version 2.0rc2 the 'preset' option no longer defaults to 'date'. If you want to use the date preset, you must explicitly specify. 'ampm' and 'seconds' options were also removed. Use the timeWheels option instead
Starting from version 2.0rc2 the 'preset' option no longer defaults to 'date'. If you want to use the date preset, you must explicitly specify. 'ampm' and 'seconds' options were also removed. Use the timeWheels option instead
Having trouble? Ask for help.
Getting Started
Mobiscroll Core
Mobiscroll Instance
Datetime Scroller
Select Scroller
List Scroller
Rating Scroller
Writing Custom Components
Writing Themes
Writing Language Modules
Mobiscroll Core Documentation
These are the core functions, options, events and methods that are available, if they are not overriden by a preset implementation.
Utility functions
| Name | Parameters | Description |
|---|---|---|
| setDefaults | function(settings) | Set settings for all scroller instances |
Options
Options for controlling the modal dialog button labels and header text.
| Name | Type | Default value | Description |
|---|---|---|---|
| cancelText | String | 'Cancel' | Text for Cancel button |
| setText | String | 'Set' | Text for Set button |
| headerText | Mixed | '{value}' | Specifies a custom string which appears in the popup header. If the string contains '{value}' substring, it is replaced with the formatted value of the scroller. If it's set to false, the header is hidden. If a function is passed, it receives the formatted value as parameter and the returned value appears in the header |
| lang | String | 'en-US' | Language of the scroller. Based on the language string the scroller loads the language based default settings from the language modules. |
| Name | Type | Default value | Description |
|---|---|---|---|
| anchor | jQuery Object | undefined | Specifies the anchor element for positioning, if 'display' is set to 'bubble'. If undefined, it defaults to the element on which the scroller was called. |
| animate | String | undefined | Animation to use for show/hide (if display is not inline). Possible values:
|
| delay | Integer | 300 | Specifies the speed in milliseconds to change values in clickpick mode with tap & hold |
| disabled | Boolean | false | Disables (true) or enables (false) the scroller. Can be set when initialising the scroller |
| display | String | 'modal' |
Controls the positioning of the scroller. Possible options:
|
| height | Number | 40 | Height in pixels of one row on the wheel |
| mode | String | 'scroller' | Option to choose between modes. Possible modes: 'scroller' - standard behaviour, 'clickpick' - '+' and '-' buttons |
| preset | String | '' | Preset configurations for date, time and datetime pickers or select replacement, possible values: 'date', 'time', 'datetime', 'select', 'rating'. It is possible to write custom presets. |
| scrollLock | Boolean | true | Disables page scrolling on touchmove (if not in inline mode)
At the time of 2.1-beta on Android 2.3 fast touchmoves sometimes causes pagescroll which may cause that the scroller gets out of the viewport.
|
| readonly | Boolean or Array of Booleans | false | If true, the scroller is displayed, but wheels are not moveable. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - disables the first wheel. |
| rows | Number | 3 | Number of visible rows on the wheel |
| showLabel | Boolean | true | Show/hide labels above wheels |
| showOnFocus | Boolean | true | Pops up the scroller on input focus |
| theme | String | '' | Sets the scroller's visual appearance. Supplied themes:
|
| wheels | Object | [] | Wheels configuration. Example: [ { 'Label 1': { x: 'x', y: 'y', z: 'z' }, 'Label 2': { a: 'a', b: 'b' } }, { 'Label 3': { 1: '1', 2: '2' }, 'Label 4': { 4: '4', 5: '5' } } ] |
| width | Number | 80 | Minimum width in pixels of the wheels, expand to fit values and labels |
Events
| Name | Parameters | Description |
|---|---|---|
| formatResult | function(data) | Receives selected scroller values as an array and must return a string to set as the value of the input element. By default it concatenates the values to a string, or, if a preset is selected, formats the date/time according to dateFormat/timeFormat option |
| onCancel | function(valueText, inst) | Allows you to define your own event when cancel is pressed. The function receives the selected value as text and the scroller instance as parameters |
| onChange | function(valueText, inst) | Allows you to define your own event when a wheel value is changed. The function receives the selected value as text and the scroller instance as parameters |
| onClose | function(valueText, inst) | Allows you to define your own event when the scroller is closed. The function receives the selected value as text and the scroller instance as parameters. If returns false, close is prevented |
| onSelect | function(valueText, inst) | Allows you to define your own event when a scroller value is set. The function receives the selected value as text and the scroller instance as parameters |
| onShow | function(html, inst) | Gets called when the scroller appears. The function receives the jQuery object containing the generated html and the scroller instance as parameters |
| parseValue | function(valueText) | Receives a string as parameter and must return an array which represents the selected scroller values. |
| validate | function(html, index, time) | Gets called on initialization and on every wheel change, can be used to validate the selected values. Has 3 parameters: html - jQuery object containing the generated html, index - index of the changed wheel (undefined on initial call), time - animation time of the wheel (if wheel is still moving) |
Methods
| Name | Parameters | Description |
|---|---|---|
| destroy | .scroller('destroy') | Remove the scroller functionality completely. This will return the element back to its pre-init state |
| disable | .scroller('disable') | Disable the scroller |
| enable | .scroller('enable') | Enable the scroller |
| getValue | .scroller('getValue') | Returns the selected scroller values as an array |
| hide | .scroller('hide') | Hide the scroller |
| isDisabled | .scroller('isDisabled') | Determine whether a scroller has been disabled. |
| option | .scroller('option', optionName, value) or .scroller('option', options) | Set scroller options |
| setValue | .scroller('setValue', data, fill, time) | Sets the scroller values from the data parameter passed as array. If the 'fill' parameter is true, the associated input field is also updated with the new value. The 'time' parameter specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if 'time' is not specified |
| show | .scroller('show') | Show the scroller |
