Contents

Select

Starting from 2.5.0 multiple select lists are also supported. If the "multiple" attribute is set on the original select element, multiple selection is automatically enabled.

Basic usage

Javascript
mobiscroll.select('#select', {
    theme: 'ios', 
    display: 'bottom',
    group: true
});
HTML
<select id="select">
    <optgroup label="A">
        <option value="Alan">Alan</option>
        <option value="Anderson">Anderson</option>
    </optgroup>
    <optgroup label="E">
        <option value="Eva">Eva</option>
        <option value="Esther">Esther</option>
    </optgroup>
    <optgroup label="M">
        <option value="Michael">Michael</option>
        <option value="Margared">Margared</option>
    </optgroup>
</select>
If you're using jQuery Mobile, it will automatically enhance the select elements on the page, which conflicts with Mobiscroll Select. To be able to use it, the data-role="none" attribute must be set to the select element, to prevent jQuery Mobile enhancement.

Options

Name Type Default value Description
anchor String or HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'bubble'. If undefined, it defaults to the element on which the component was initialized.
animate String or Boolean undefined Animation to use for show/hide (if display is not inline). Possible values:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
If false, turns the animation off.
buttons Array ['set', 'cancel'] Buttons to display. Each item in the array will be a button. A button can be specified as a string, or as a button object.

If a string, it must be one of the predifined buttons:
  • 'set' - Sets the value.
  • 'clear' - Clears the value.
  • 'cancel' - Dismisses the popup.
To modify the text of the predfined buttons, you can use the setText, clearText , cancelText settings.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Sets the value.
    • 'clear' - Clears the value.
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
Predefined and custom buttons example
buttons: [ 
    'set',
    { 
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event, inst) { 
            alert('Custom button clicked!'); 
        } 
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    { 
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
circular Boolean or Array undefined If true, the scroll wheels are circular. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - sets the first wheel circular. If not specified, if a wheel has more values than the number of displayed rows, the scroll wheel becomes circular.
closeOnOverlayTap Boolean true If true, the popup is closed on overlay tap/click.
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
counter Boolean false If true the number of selected items will be displayed in the header.
cssClass String undefined Applies custom css class to highest level element.
data Array of Objects, Object undefined Contains the data for initializing the component without using a native html select element.

The array objects can have the following properties:
  • text - Specify the text of the element.
  • value - Specify the value of the element.
  • group - Specify the group name.
  • html - The specified markup will be shown instead of the text in the wheels.
  • disabled - If true the element will be disabled.
Example for data array:
data: [
        {
            text: 'Paris',
            value: '1',
            group: 'Europe'
        },
        {
            text: 'New York',
            value: '2',
            group: 'America',
            disabled: true
        }
    ]

If it is specified as an object the following properties can be set:
  • url - Specify the remote data source.
  • dataField - The field from the response which contains the needed data.
  • dataType - Specify the data type of the remote data. It could be 'json' or 'jsonp'. The 'jsonp' is required for cross-domain requests and use 'json' for same-domain requests.
  • processResponse - A function which is called to process and return the data from the response.
  • remoteFilter - If true the filtering will be managed from the remote source. The filter query will be passed as a parameter.

Example for data object:
data: {
        url: 'http://example.com/airports/',
        remoteFilter: true,
        dataType: 'jsonp',
        processResponse: function (data) {
            // process the response here 
        }
    }
dataGroup String 'group' Defines the data object group property name.
dataText String 'text' Defines the data object text property name.
dataValue String 'value' Defines the data object value property name.
disabled Boolean false Initial disabled state of the component.
display String 'center' Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - The component appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.
filter Boolean true If true, a filter input will be shown above the wheels. Typing in the input will filter the wheel values.
focusOnClose Boolean, String or jQuery Object true Element to focus after the popup is closed. If undefined, the original element will be focused. If false, no focusing will occur.
focusTrap Boolean true If not in inline mode, focus won't be allowed to leave the popup.
group Object undefined Group select will available if the select contains optgroups (or the data object has a group property), and the group setting is true or an object with one ore more of the following properties:
  • header: If true, group headers will be shown on the option wheel.
  • groupWheel: If true, two wheels are generated, the first contains the optgroup labels or the data.group property values, and the second one contains the options of the selected group.
  • clustered: If true, the option wheel will contain only the options from the selected group, otherwise it will contain all the available options and the group wheel is updated whenever the option wheel is scrolled to an option from another group.
Sample configuration:
group: {
    groupWheel: true,
    header: false,
    clustered: true
}
groupLabel String 'Groups' Label for the optgroup wheel.
headerText Mixed false Specifies a custom string which appears in the popup header.
If the string contains the '{value}' substring, it is replaced with the formatted value of the select.
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.
The default value depends on the theme:

Mobiscroll: false
Android Holo: {value}
Bootstrap: {value}
iOS: false
jQuery Mobile: {value}
Material: false
Windows Phone: false
height Number 40 Height in pixels of one item on the wheel. The default value depends on the theme:

Mobiscroll: 40
Android Holo: 36
Bootstrap: 40
iOS: 34
jQuery Mobile: 40
Material: 40
Windows Phone: 76
inputClass String '' Css class(es) to style the input which is shown instead of the original select element.
invalid Array [] An array of strings containing the invalid select values. If empty, the preset takes the disabled options from the original select element.
label String undefined Sets the label of the wheel. If undefined, the label is taken from the original html select element's label, and falls back to the select element's name attribute, if the label doesn't exist.
layout String undefined Sets the layout of the component. 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 separately.
minWidth Number or Array 80 Minimum width of the wheels in pixels. If number, it is applied to all wheels, if an array, it is applied to each wheel separately. The default value depends on the theme:

Mobiscroll: 80
Android Holo: 76
Bootstrap: 80
iOS: 55
jQuery Mobile: 80
Material: 80
Windows Phone: 76
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.
placeholder String undefined Placeholder string for the generated input.
readonly Boolean or Array false If true, the component is displayed, but the values are not selectable. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - sets the first wheel readonly.
rows Number 3 Number of visible rows on the wheel. The default value depends on the theme:

Mobiscroll: 5
Android Holo: 5
Bootstrap: 3
iOS: 5
jQuery Mobile: 3
Material: 3
Windows Phone: 3
select String or Number 'single' Defines the selection of the items. Possible values:
  • 'single' - Only one item can be selected at once.
  • 'multiple' - Multiple items can be selected.
  • Numeric value - The maximum number of items that can be selected.
showInput Boolean true Display an input field which is populated with the selected value of the select.
showLabel Boolean true Show/hide labels above wheels
showOnFocus Boolean false Pops up the component on element focus.
showOnTap Boolean true Pops up the component on element tap.
showScrollArrows Boolean false Display scroll arrows for the wheels.
theme String undefined Sets the visual appearance of the component.

If it is 'auto' or undefined, the theme will automatically be chosen based on the platform. If the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'android-holo' - Android 4.x theme
  • 'android-holo-light' - Android 4.x theme (light version)
  • 'bootstrap' - Bootstrap themes
  • 'ios' - new iOS 7, 8, 9 theme
  • 'material' - Material theme (Android 5.x)
  • 'material-dark' - Material dark theme (Android 5.x)
  • 'jqm' - Integrates with jQuery Mobile look & feel
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll Dark 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 select markup with the theme name and the 'mbsc' prefix, e.g.: .mbsc-my-theme .dwwr { /* My CSS */ }, and set the theme option to 'my-theme'
Make sure that the theme you set is included in the downloaded package.
width Number or Array 70 Exact width of the wheels, in pixels. Wheel content will be truncated, if it exceeds the width. If number, it is applied to all wheels, if an array, it is applied to each wheel separately.

Setting options runtime (changing options dynamically)

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

    Javascript
    // Modify options
    $('#mobiscroll').mobiscroll('option', {
        theme: 'ios',
        lang: 'de'
    });
    HTML
    <input id="mobiscroll"/>
  2. Modify directly the settings object.

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

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

Events

Name Description
onBeforeClose(event, inst) Triggered before the component closes. Close can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
    • button: String - The name of the button which triggered the component to close ('set', or 'cancel').
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onBeforeClose: function (event, inst) {
    }
});
onBeforeShow(event, inst) Triggered before the component is shown. It is useful if you want to modify the settings object before generating the markup. It can be used also to prevent the showing the control by returning false.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onBeforeShow: function (event, inst) {
    }
});
onCancel(event, inst) Allows you to define your own event when cancel is pressed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onCancel: function (event, inst) {
    }
});
onChange(event, inst) Allows you to define your own event when a wheel value is changed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onChange: function (event, inst) {
    }
});
onClear(event, inst) Triggered when the value is cleared.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onClear: function (event, inst) {
    }
});
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onClose: function (event, inst) {
    }
});
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onDestroy: function (event, inst) {
    }
});
onFilter(event, inst) Gets fired when the filter input gets updated. Filter can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • filterText: the filter input's value
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onFilter: function (event, inst) {
    }
});
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onInit: function (event, inst) {
    }
});
onItemTap(event, inst) Triggered when the user taps an item on the wheel.

Parameters

  • event: Object - The event object has the following properties:
    • target: HTMLElement - The DOM element of the tapped item.
    • selected: Boolean - Selected state of the tapped item.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onItemTap: function (event, inst) {
    }
});
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onMarkupReady: function (event, inst) {
    }
});
onPosition(event, inst) Triggered when the component is positioned (on initial show and resize / orientation change).

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onPosition: function (event, inst) {
    }
});
onSet(event, inst) Triggered when a value is set.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onSet: function (event, inst) {
    }
});
onShow(event, inst) Triggered when the component is shown.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the select.

Example

$('#mobiscroll').mobiscroll().select({
    onShow: function (event, inst) {
    }
});

Methods

Name Description
cancel() Hides the select and also invokes the onCancel event.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('cancel');

// With instance
mobiscrollInstance.cancel();
clear() Clears the select value.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('clear');

// With instance
mobiscrollInstance.clear();
destroy() Destroys the component. This will return the element back to its pre-init state.

Returns: Object

  • Returns the element back to its pre-init state.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('destroy');

// With instance
mobiscrollInstance.destroy();
disable() Disables the select.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('disable');

// With instance
mobiscrollInstance.disable();
enable() Enables the select.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('enable');

// With instance
mobiscrollInstance.enable();
getArrayVal([temp]) Returns the selected select wheel values as an array.

Parameters

  • temp (Optional): Boolean - If true, temporary values are returned (prior clicking the Set button).

Returns: Array

  • An array containing the wheel values.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('getArrayVal');

// With instance
mobiscrollInstance.getArrayVal();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('getInst');

// With instance
mobiscrollInstance.getInst();
getVal([ temp ] [, group ]) Returns the selected value or the list of the selected values (if multiple select).

Parameters

  • temp (Optional): Boolean - If true, returns the temporary values (prior clicking the Set button).
  • group (Optional): Boolean - If true, returns an array with the group and value in the order of the wheels.

Returns: String or Array

  • The selected value or an array containing the selected values.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('getVal');

// With instance
mobiscrollInstance.getVal();
hide([ prevAnim ] [, btn ]) Hides the component.

Parameters

  • prevAnim (Optional): Boolean - If true, hide will not be animated.
  • btn (Optional): String - Specifies which button caused the component to hide, and it's passed to the onBeforeClose event.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('hide');

// With instance
mobiscrollInstance.hide();
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('isVisible');

// With instance
mobiscrollInstance.isVisible();
option(options) Sets one or more options for the component.

Parameters

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

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('option', {
    display: 'bottom',
    lang: 'de'
});

// With instancee
mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});
position([check]) Recalculates the position of the component (if not inline).

Parameters

  • check (Optional): Boolean - If true, the function checks if viewport size changed after last position call, if false or ommitted, position is recalculated anyway.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('position');

// With instance
mobiscrollInstance.position();
refresh() Refreshes the select wheels based on the data option values.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('refresh');

// With instance
mobiscrollInstance.refresh();
select() Hides the select and also invokes the onSelect event.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('select');

// With instance
mobiscrollInstance.select();
setArrayVal (values [, fill ] [, change ] [, temp ] [, time ]) Sets the select wheel values from the values parameter passed as array.

Parameters

  • values: Array - An array containing the wheel values.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered on the input element.
  • temp (Optional): Boolean - If true, only temporary values are set.
  • time (Optional): Number - 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.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('setArrayVal', [4, 5]);

// With instance
mobiscrollInstance.setArrayVal([4, 5]);
setVal(value [, fill ] [, change ] [, temp ] [, time ]) Sets the selected value.

Parameters

  • value: String or Array - In case of a simple or grouped select value must be the value to be selected, in case of a multiple select value must be an array with the selected values.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered.
  • temp (Optional): Boolean - If true, only temporary values are set.
  • time (Optional): Number - 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.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('setVal', 5);

// With instance
mobiscrollInstance.setVal(5);
show([ prevAnim ] [, prevFocus ]) Shows the component.

Parameters

  • prevAnim (Optional): Boolean - If true, show will not be animated.
  • prevFocus (Optional): Boolean - If true, the popup will not be focused right after show.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('show');

// With instance
mobiscrollInstance.show();
tap(el, handler) Attaches the handler function to the tap event of element el.

Parameters

  • el: Object - The element with tap event.
  • handler: Function - If the action was initiated with touch event, handler is called on touchend, otherwise on click.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('tap', $('#element'), function () { alert("It's a tap!"); });

// With instance
mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button.
clearText String 'Clear' Text for Clear button.
filterEmptyText String 'No results' Text for the empty state of the select wheels.
filterPlaceholderText String 'Type to filter' Text for the select filter input placeholder.
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 select. 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 component. Based on the language string the component 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)
  • 'ar' - Arabic
  • 'bg' - Bulgarian
  • 'ca' - Catalan
  • 'cs' - Czech
  • 'zh' - Chinese
  • 'da' - Danish
  • 'de' - German
  • 'el' - Greek
  • 'es' - Spanish
  • 'fa' - Farsi
  • 'fi' - Suomi
  • 'fr' - French
  • 'he' - Hebrew
  • 'hi' - Hindi
  • 'hr' - Croatian
  • 'hu' - Hungarian
  • 'it' - Italian
  • 'ja' - Japanese
  • 'ko' - Korean
  • 'lt' - Lithuanian
  • 'nl' - Dutch
  • 'no' - Norwegian
  • 'pl' - Polish
  • 'pt-BR' - Brazilian Portuguese
  • 'pt-PT' - European Portuguese
  • 'ro' - Romanian
  • 'ru' - Russian
  • 'ru-UA' - Russian (UA)
  • 'sk' - Slovak
  • 'sr' - Serbian
  • 'sv' - Swedish
  • 'tr' - Turkish
  • 'vi' - Vietnamese
rtl Boolean false Right to left display.
selectedText String '{count} selected' Specifies the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items.
setText String 'Set' Text for Set button.