Mobiscroll 2.10.0 Documentation

Last updated Friday, April 11, 2014

Welcome to the Mobiscroll API Reference. You can find the most up to date information about usage and customization options here.

Requires jQuery >= 1.7, Zepto.js >= 1.0 or App Framework (former jqMobi) >= 1.2

Starting from version 2.2 due to naming collisions with other frameworks the $('#selector').mobiscroll() notation is introduced instead of $('#selector').scroller(). $('#selector').scroller() also works, if there is no collision, but it is considered deprecated and will be removed in the future.

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.


Mobiscroll Core Documentation

These are the core functions, options, events and methods that are available, if they are not overriden by a preset implementation.

Global functions

else
Name Parameters Description
$.mobiscroll.setDefaults function(settings) Set settings for all scroller instances.

Global properties

Name Type Description
$.mobiscroll.activeInstance Mobiscroll object Stores the currently active mobiscroll instance (expcept inline instances), or null if there is no active instance.

Localization

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button.
clearText String 'Clear' Text for Clear 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.
Supported languages:
  • 'en' or 'en-US' or undefined - English
  • 'en-UK' or 'en-GB' - English (UK)
  • 'cs' - Czech
  • 'zh' - Chinese
  • 'de' - German
  • 'es' - Spanish
  • 'fr' - French
  • 'it' - Italian
  • 'ja' - Japanese
  • 'hu' - Hungarian
  • 'nl' - Dutch
  • 'no' - Norwegian
  • 'pt-BR' - Brazilian Portuguese
  • 'pt-PT' - European Portuguese
  • 'sv' - Swedish
  • 'tr' - Turkish

Options

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:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
Requires the animation plugin.
buttons Array ['set', 'cancel'] Buttons to display. Predefined buttons are: 'set', 'clear', 'cancel'. Custom buttons can also be specified:
buttons: [ 
    'set',
    { text: 'Custom', handler: function (event, inst) { alert('Custom button clicked!'); } }
    'cancel'
]
                
closeOnOverlay Boolean true If true, scroller is closed on overlay tap/click.
context String 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a jQuery selector string or a jQuery object.
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:
  • 'modal' - Scroller appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, scroller is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - Scroller appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - Scroller appears docked to the top of the viewport.
  • 'bottom' - Scroller appears docked to the bottom of the viewport.
fixedWidth Number or Array undefined Width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately.
height Number 40 Height in pixels of one row on the wheel
layout String undefined Sets the scroller layout. Possible values:
  • 'liquid' - Wheels will expand to the maximum available width, but will not exceed the width set by the maxWidth setting. If maxWidth is not specified, the total width of all wheels will not exceed 600px. In 'top' or 'bottom' display mode this is the default behavior.
  • 'fixed' or undefined - Wheels will expand to the size of the longest wheel value, but will not exceed the width set by the maxWidth setting.
maxWidth Number or Array undefined Maximum width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately.
minWidth Number or Array undefined Minimum width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel sepparately.
mode String 'scroller' Option to choose between modes. Possible values:
  • 'scroller' - standard behaviour.
  • 'clickpick' - '+' and '-' buttons.
  • 'mixed' - wheels can be scrolled, '+' and '-' buttons are also visible.
multiline Number 1 If greater than 1, the wheel item's content will be wrapped into the specified number of lines. If the content is shorter, it will remain vertically centered.
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
showOnTap Boolean true Pops up the scroller on element tap
tap Boolean true Fire button actions on tap instead of click (on touch devices)
theme String '' Sets the scroller's visual appearance. Supplied themes:
  • 'android' - Android 2.x theme
  • 'android-ics' - Android 4.x theme
  • 'android-ics light' - Android 4.x theme (light version)
  • 'bootstrap' - Bootstrap themes
  • 'ios' - iOS theme
  • 'ios7' - iOS 7 theme
  • 'jqm' - Integrates with jQuery Mobile look & feel
  • 'sense-ui' - HTC Sense UI theme
  • 'sense5' - HTC Sense 5 theme
  • 'wp' - Windows Phone Metro UI theme
  • 'wp light' - Windows Phone Metro UI theme (light version)
It's possible to create custom themes in css by prefixing any css class used in the scroller markup with the theme name, e.g.: .my-theme .dww { / My CSS / }, and set the theme option to 'my-theme'
wheels Object [] Wheels configuration. If keys array is omitted, the values array is used for keys as well.

Starting from 2.6.0 a new format was introduced for passing the wheels. The old format is still supported but it is considered deprecated and will be removed in the future.

Below is an example with 2 wheel groups, each containing 2 wheels.
wheels: [ // Wheel groups array
    [ // First wheel group
        { // Wheel object
            label: 'Label 1', 
            keys: [1, 2, 3],  
            values: ['x', 'y', 'z'], 
        }, 
        { // Wheel object
            label: 'Label 2', 
            keys: [1, 2],  
            values: ['a', 'b'], 
        } 
    ], 
    [ // Second wheel group
        { // Wheel object
            label: 'Label 3', 
            values: [1, 2], 
        }, 
        { // Wheel object 
            label: 'Label 4', 
            values: [4, 5], 
        } 
    ]
]
width Number 70
Starting from 2.8.0 the width setting is deprecated and will be removed in 3.0. Use the new minWidth setting instead.

Minimum width in pixels of the wheels, expand to fit values and labels

Theme options

Name Type Default value Description
jQuery Mobile Theme
jqmBorder String 'a' Swatch for picker border.
jqmBody String 'c' Swatch for picker body.
jqmHeader String 'b' Swatch for picker header.
jqmWheel String 'd' Swatch for wheel background (clickpick mode only).
jqmClickPick String 'c' Swatch for clickpick buttons.
jqmSet String 'b' Swatch for set button.
jqmCancel String 'c' Swatch for cancel button.
Windows Phone Theme
accent String 'none' Specifies the accent color of the theme. Possible values: 'lime', 'green', 'emerald', 'teal', 'cyan', 'cobalt', 'indigo', 'violet', 'pink', 'magenta', 'crimson', 'red', 'orange', 'amber', 'yellow', 'brown', 'olive', 'steel', 'mauve', 'sienna'.

Events

Name Parameters Description
onBeforeShow function(inst) Gets called before the scroller appears. It is usefull if you want to modify the settings object before generating the markup (e.g. change the wheel values). The function receives the scroller instance as parameters
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, btn, inst) Allows you to define your own event when the scroller is closed. The function receives the selected value as text, the button, which triggered the scroller to close ('set', or 'cancel') and the scroller instance as parameters. If returns false, close is prevented.
onDestroy function(inst) Gets called when the mobiscroll instance is destroyed. The function receives the scroller instance as parameter.
onMarkupReady function(html, inst) Allows you to define your own event when the html markup of the scroller is generated, but it is not yet shown. It is usefull, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs. The function receives the jQuery object containing the generated html and the scroller instance as parameters. If returns false, close is prevented.
onPosition function(html, inst) Gets called when the scroller is positioned (on initial show and resize / orientation change). The function receives the jQuery object containing the generated html and the scroller instance as parameters
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, valueText, inst) Gets called when the scroller appears. The function receives the jQuery object containing the generated html, the formatted value and the scroller instance as parameters
onValueTap function(item, inst) Gets called when the user taps on a value on the wheel. The function receives the jQuery object containing the html of the tapped item and the scroller instance as parameters
validate function(html, index, inst) 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), inst - mobiscroll instance

Methods

Name Parameters Description
cancel .mobiscroll('cancel') Hides the scroller and also invokes the onCancel event.
changeWheel .mobiscroll('changeWheel', indexes, time) Regenerates the wheel with the given indexes based on the option. Usefull if you want to change a wheel dinamically based on another wheel's currently selected value. The time parameter specifies the animation time to scroll the new wheel to the selected value.
destroy .mobiscroll('destroy') Remove the scroller functionality completely. This will return the element back to its pre-init state.
disable .mobiscroll('disable') Disables the scroller.
enable .mobiscroll('enable') Enables the scroller.
getInst .mobiscroll('getInst') Returns the object instance.
getValue .mobiscroll('getValue') Returns the selected scroller values as an array.
getValues .mobiscroll('getValues') Returns the list of selected values if multiple selection is implemented in the preset.
hide .mobiscroll('hide', prevAnim, btn) Hides the scroller. If prevAnim is true, hide will not be animated. The optional btn parameter specifies which button caused the scroller to hide, and it's passed to the onClose event.
init .mobiscroll('init', settings) Initializes the scroller. Gets called when creating a new scroller instance, or updating the options of an existing scroller instance with the settings parameter.
isVisible .mobiscroll('isVisible') Returns a boolean indicating whether the scroller is visible or not.
option .mobiscroll('option', optionName, value) or .mobiscroll('option', options) Set scroller options
position .mobiscroll('position', check) Recalculates scroller position (if not inline). If check is true, the function checks if window size changed after last position call, if false or ommitted, position is recalculated anyway.
select .mobiscroll('select') Hides the scroller and also invokes the onSelect event.
setValue .mobiscroll('setValue', values, fill, time, temp) Sets the scroller values from the values 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 omitted or 0. If temp is true, only temporary values are set.
show .mobiscroll('show', prevAnim) Shows the scroller. If prevAnim is true, show will not be animated.
tap .mobiscroll('tap', el, handler) Attaches the handler function to the tap event of element el. If the action was initiated with touch event, handler is called on touchend, otherwise on click.
trigger .mobiscroll('trigger', name, params) Calls the name event with params (Array) as parameters, if it is defined in preset, theme or user settings. The instance is always added to the end of the parameter list.

Setting options runtime

There are two ways to modify options after initalization

  1. Using the option method.

    The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).

    // Modify one option
    $('#scroller').mobiscroll('option', 'mode', 'clickpick');
    
    // Modify multiple options
    $('#scroller').mobiscroll('option', { mode: 'clickpick', rows: 5 });
    
  2. Modify directly the inst.settings object.

    Useful when changing dynamic settings, which do not need redraw (e.g. readonly, calendar marked days).

    // Get instrance and modify a setting
    var inst = $('#scroller').mobiscroll('getInst');
    inst.settings.readonly = true;
    
    // Modify settings in an event
    $('#scroller').mobiscroll({
        onBeforeShow: function (inst) {
            inst.settings.readonly = true;
        }
    });
    

Conversion functions

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
parseValue function(valueText) Receives a string as parameter and must return an array which represents the selected scroller values.