This version of the documentation is outdated. Check the latest version here!

Select

The Mobiscroll Select component lets you pick a single or multiple values from a list of options.

Basic usage

The following example will create a simple select with 3 options to choose a country from:

HTML Markup
<select id="my-select">
  <option value="USA">United State of America</option>
  <option value="CAN">Canada</option>
  <option value="MEX">Mexico</option>
</select>
Javascript code
$(function() {
    $('#my-select').mobiscroll().select();
})

Data binding

There are multiple ways to pass the options to the Mobiscroll Select component. The following section describes these methods in detail.

The data option

The data option receives an array of strings or an array of objects containing a text, a value and optionally a group property.

The text must be a string, which will show up on the wheels. The value can be any kind of object (string, number, object, etc...), that will be the selected value when selecting it on the select.

The group property must be a string, that is used to group together a number of options. The options that have the same string specified by the group property will be grouped together. When groups are specified in the data, a header will be shown at the top of each group with the text specified in the group property. Additionally, when using the showGroupWheel option, an additional wheel will be shown, with the groups to help navigation.

Check out the Grouping section for more details.

When an array of string is passed to the data option, it is treated as both the text and the value would be the particular array item.

const strArray = ['USA', 'Canada', 'Mexico'];
// is the same as:
const objArray = [{ text: 'USA', value: 'USA'}, { text: 'Canada', value: 'Canada'}, { text: 'Mexico', value: 'Mexico' }];

In the above example the two arrays will show the same 3 countries to select from, and the selected value will also be the country's name as string.

Number value example
<label>Pick Department
    <input id="my-input" type="text" />
</label>
$(function() {
    $('#my-input').mobiscroll().select({
        data: [
            { text: 'Sales', value: 1 },
            { text: 'Support', value: 2},
            { text: 'Development', value: 3},
        ],
        onChange: function(ev, inst) {
            console.log(ev.value); // the selected ID
        },
    });
})
Object value example
<label>Pick User
    <input id="my-input" type="text" />
</label>
$(function() {
    $('#my-input').mobiscroll().select({
        data: [
            { text: 'Alice', value: { id: 123, fullName: 'Alice Cooper' }},
            { text: 'Brandon', value: { id: 456, fullName: 'Brandon Lee' }},
            { text: 'Louisa', value: { id: 789, fullName: 'Louisa Crawford'}},
        ],
        onChange: function(ev, inst) {
            console.log(ev.value); // the selected user object
        },
    });
})

Group options

Through the data option, with each select item can be passed an optional group property. This group property is a string, that defines the group of the item. When the group is passed to any of the items, the whole data is treated as grouped and a header will be rendered above each group on the select wheels. The header will contain the group name as specified in the group property.

Assigning groups to items
var myCountries = [{
    text: 'United Kingdom',
    value: 'GB',
}, {
    text: 'France',
    value: 'FR',
    group: 'Europe'
}, {
    text: 'Hungary',
    value: 'HU',
    group: 'Europe'
}, {
    text: 'United States of America',
    value: 'US',
    group: 'America'
}];
$('#my-input').mobiscroll().select({ data: myCountries });

Another possibility to define groups is, when the select component is initialized on a native <select> element. In this case the native <optgroup> element is to be used by defining a label attribute on it.

Using optgroup elements to define groups
<select id="my-select">
    <option value="GB">United Kingdom</option>
    <optgroup label="European Union">
        <option value="FR">France</option>
        <option value="HU">Hungary</option>
    </optgroup>
    <optgroup label="America">
        <option value="US">United States of America</option>
    </optgroup>
</select>
$('#my-select').mobiscroll().select({});

Furthermore an additional "group wheel" can be also rendered with the showGroupWheel option set to true. The group wheel items will be the group property values or the optgroup label attributes, and will help in navigating the option wheel.

Rendering the group wheel
$('#my-input').mobiscroll().select({ data: myCountries, showGroupWheel: true });

Data through markup

The Mobiscroll Select component can be initialized on a <select> element, in which case it does not require the data option to be passed. The data will be read from the <option> elements.

Initializing on native select
<label>Gender
    <select id="gender">
        <option value="female">Female</option>
        <option value="male">Male</option>
    </select>
</label>
$('#gender').mobiscroll().select();
Group select
<label>Country
    <select id="countries">
        <optgroup label="Europe">
            <option value="fr">France</option>
            <option value="hu">Hungary</option>
        </optgroup>
        <optgroup label="Asia">
            <option value="ch">China</option>
            <option value="ja">Japan</option>
        </optgroup>
    </select>
</label>
$('#countries').mobiscroll().select();

Dynamic or Async Data

The select component supports dynamic data binding. For cases when the data is not immediately available or when the data changes with time (new options are added, or others removed) this feature is the most usefull.

Dynamic Markup

As mentioned earlier in the data binding section, the selection data can be passed to the select via markup: using a select and option HTML elements.

When updating the markup dynamically after the select component was initialized, the reloadOptionElements() method has to be called on the select instance so it learns about the new options.

Data option

When using the select with the data option, updating the data can be done, with the setOptions() function of the select instance.

$('#my-input').mobiscroll().select({
    data: [],
});
const inst = $('#my-input').mobiscroll('getInst'); // get the instance of the select component
inst.setOptions({ data: ['Item 1', 'Item 2', 'Item 3']}); // update the component with new data

Filtering

Filtering can be turned on with the filter option. It is very usefull when using large datasets and you want to find a particular item.

When filtering is on, a filter input is rendered above the select options. The placeholder of the input can be customized and localized with the filterPlaceholderText option.
Typing a text in the input filters the options you can select from. Also, with each change on the filter input text, the onFilter event is triggered.

When no items match the filter the Mobiscroll Select will show a "No results" message, that can be customized and localized with the filterEmptyText option.

Remote Filtering

Server side filtering can be implemented by customizing the filtering. Returning false from the onFilter event handler function will prevent the filtering of the option items. A request can be made to the server with the filterText and the returned data can be set to the Mobiscroll Select dynamically.

Custom (remote) filtering example
$('#my-input').mobiscroll().select({
    data: [],
    filter: true,
    onFilter: function(ev, inst) {
        var phrase = ev.filterText;
        // create a request to your server endpoint
        youCustomFilter(phrase, function callback(data) { // update the component with the response data
            inst.setOptions({ data: data });
        });
        return false;
    }
});

function yourCustomFilter(phrase, callback) {
    // your custom filtering implementation here
    // ...
    callback(data);
}

Single vs. Multi Select

The Mobiscroll Select component supports multi selection too. By default it operates in single selection mode, but multi selection can be turned on with the selectMultiple option.

Multi-Select example
$('#my-input').mobiscroll().select({
    data: ['Free ticket', 'Free Drink', 'Free Hug'],
    selectMultiple: true,
    onChange: function(ev, inst) {
        console.log(inst.getVal()); // the value will be an array with the selected values
    }
});

Invalid items

Invalid items are items that cannot be selected. They appear disabled on the wheels and when clicked, a selection will not happen.

Invalid items can be set using the invalid option or the data option. The invalid option takes an array of values and disables those values. When using the data option, each item can take a disables property, that disables that item.

Invalid example
$('#my-input').mobiscroll().select({
    data: [{ value: 'sug', text: 'Sugar'}, { value: 'hon', disabled: true, text: 'Honey'}, { value: 'cre', text: 'Cream' }],
    invalid: ['sug'],
    onChange: function(ev, inst) {
        console.log(inst.getVal());
    }
});

Display modes

The select component can operate in two ways from the display option's point of view:

Here comes the center, top, bottom displays, and also the anchored display when the touchUi option is true.

In these display modes, the picker shows up as a modal picker. When open, the selected value is stored as a temporary value until the set button is pressed. At that point the picker is closed and the value is commited to the input.

The above mentioned temporary value, when required, can be manipulated using the getTempVal() and setTempVal() instance methods. Whe the temporary value changes the onTempChange event is raised.

To get or change the selected value, that's set to the input, the getVal and setVal instance methods are available to use.

"Live" selection

Here come the inline display (which displays as an embedded control) and the anchored display when the touchUi options is false (on desktop devices).

In this case by default there is no set button to commit the value, so there's no temporary value like when the modal displays are used. What is shown on the picker, that is set directly to the input

To get or change the selected value, that's set to the input, the getVal and setVal instance methods are available to use.

Customizing the input

When initializing the Select component on a native select element, by default that element will be hidden and an input element is rendered that will hold the selection text. Also this input element gets the focus and click handlers that will open the picker.

<select id="my-select">
    <option value="lon">London</option>
    <option value="ber">Berlin</option>
    <option value="par">Paris</option>
</select>
$('#my-select').mobiscroll().select({ theme: 'ios' });

You can use any custom input with the select component using the inputElement option. Passing another element to it, the default input won't be rendered. The passed element will get the event handlers to open the picker, and also the selected value's text will be written to it as well.

<input id="my-custom-input" placeholder="Click to select..." />

<select id="my-select">
    <option value="lon">London</option>
    <option value="ber">Berlin</option>
    <option value="par">Paris</option>
</select>
$('#my-select').mobiscroll().select({
    inputElement: document.getElementById('my-custom-input'),
    theme: 'ios',
});

Select Item Templating

The items can be customized using the renderItem and the itemHeight options.

The renderItem function will be used to render each item. An item parameter is passed to it, so you can access the item's data. The itemHeight option can be adjusted for styles that go beyond the default height.

Example for custom item rendering
$('#my-select').mobiscroll().select({
    data: [{
        value: 'US',
        text: 'United States of America',
        flagUrl: '//urlto/usa-flag',
    }, {
        value: 'DE',
        text: 'Germany',
        flagUrl: '//urlto/german-flag',
    }, {
        value: 'FR',
        text: 'France',
        flagUrl: '//urlto/french-flag',
    }],
    renderItem: function(item) {
        return `<div className="my-country-container">
        <img src="${item.data.flagUrl}" />
        ${item.data.text}
    </div>`;
    },
    itemHeight: 56,
});

The item parameter has the following properties:

If the data contains groups, some of the items that are passed to the custom renderer function will be header items. In these cases, there will be no data property on the header items but there will be an isGroup property that will be true.

If the group wheel is also turned on with the showGroupWheel option, the items from the group wheel that are passed to the renderer function won't have neither the dataproperty nor the isGroup property on them.

Differentiating between wheels, option and header items
data = [{
    text: 'User 1',
    value: 'username1',
    userID: 1,
    group: 'Admin'
}, {
    text: 'User 2',
    value: 'secondUser',
    userID: 2,
    group: 'Sales'
}, {
    text: 'User 3',
    value: 'thirdUser',
    userID: 3,
    group: 'Support'
}, {
    text: 'User 4',
    value: 'username4',
    userID: 4,
    group: 'Support'
}]
function renderItem(item) {
    if (!item.isGroup && !item.data) { // Group wheel item
        return `<div class="group-wheel-item">${item.display}</div>`;
    }
    if (item.isGroup) { // Option wheel - group header item
        return `<div class="group-header-item">${item.display}</div>`;
    }
    if (item.data) { // Option wheel - option item
        return `<div class="option-item">
             <div class="title">${item.data.value}</div>
             <div class="description">#${item.data.userID} ${item.data.text}</div>
        </div>`;
    }
}

Options

Name Type Default value Description
anchor HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'anchored' . If undefined, it defaults to the element on which the component was initialized.
animation String, Boolean undefined Animation to use for opening/closing of the control (if display is not inline). Possible values:
  • 'pop'
  • 'slide-down'
  • 'slide-up'
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.

When the passed array does not contain the predefined 'set' button, the auto-selection will be turned on. Selecting a value on the UI this way, will be set to the input immediately. In single select mode, tapping the value on the wheel will also close the select. Otherwise it can be closed with an overlay tap.

If a string, it must be one of the predefined buttons:
  • 'set' - Sets the value.
  • 'cancel' - Dismisses the popup.
To modify the text of the predefined buttons, you can use the setText, , cancelText options.

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.
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
  • disabled Boolean (Optional) - Sets the disabled state of the button.
  • keyCode Number, String, Array (Optional) - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predifine string values are: 'enter', 'esc' and 'space'.
Predefined and custom buttons example
buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
circular Boolean, 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.
closeOnEsc Boolean true If true, the popup is closed on ESC keypress.
closeOnOverlayClick Boolean true If true, the popup is closed on overlay tap/click.
context String, HTMLElement 'body' The DOM element in which the component is appended and positioned (if not inline). Can be a selector string or a DOM element.
cssClass String undefined Applies custom css class to the top level element.
data Array undefined

Contains the option data, that can be selected with the select component.

When it's a string array, the selectable items will be the items of the array. The strings will also appear on the scroll-wheels, and the selected values also will be the strings itselves.

When it's an object array, the objects can have the follwing properties:

  • textString - Specify the text of the element
  • valueAny - Specify the value of the element
  • groupString - Specify the group name
  • disabledBoolean - Specify the item as disabled. Disabled items cannot be selected

For a more detailed guide and examples on how to use the data option, check out the Data binding section. If you want to learn more about organising the data into groups, please see the Grouping section

Example for data array:
const strData = ['Paris', 'New York']; // string data
            const objData = [ // object data
                {
                    text: 'Paris',
                    value: 1,
                    group: 'Europe'
                },
                {
                    text: 'New York',
                    value: 2,
                    group: 'America'
                }
            ]

defaultSelection Any undefined

Default selection which appears on the picker. The provided value will not be set as picker value, it's only a pre-selection.

disabled Boolean false Initial disabled state of the component. This will take no effect in inline display mode.
display String undefined 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.
  • 'anchored' - The component appears positioned to the element defined by the anchor option. 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.

The default display mode depends on the theme, it defaults to 'bottom' for the iOS theme and to 'center' for all other themes.

In desktop mode (when the touchUi option is set to false) the default display mode is 'anchored'.

dropdown Boolean true If false, the down arrow icon is hidden.
filter Boolean false

It turns filtering on, when true. When filtering is on, a filter input will be shown above the wheels. Typing in the input will filter the select data and will also trigger the onFilter event.

The default behavior is based on the presence of the search phrase in the option labels. The onFilter event can be used to prevent the default filtering and customize the experience. Check out the Filtering Section for more use case examples.

focusOnClose Boolean, String, HTMLElement 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.
headerText Boolean, String 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.
height Number, String undefined Sets the height of the component.
inputElement HTMLElement undefined

The input element to use with the picker.
By default a standard HTML input element is rendered.
When a modal display is used (the display option is not set to 'inline') this element gets the focus/click listeners that will trigger the component to open.

inputStyle String 'underline' Defines the input rendering mode. By default the input has the underline styling. Possible values:
  • 'underline'
  • 'box'
  • 'outline'
invalid Array undefined An array of values that are invalid. Invalid options cannot be selected, and show up as disabled on the select wheels.
itemHeight Number 40 Height in pixels of one item on the wheel. The default value depends on the theme:

iOS: 34
Material: 40
Windows: 44
label String undefined Sets the label of component.
labelStyle String undefined Defines the position of the label. The default label style depends on the theme option. With the 'ios' theme the inputs have inline labels, with 'mobiscroll', 'material' and 'windows' themes the default label position is stacked. Possible values:
  • 'stacked'
  • 'inline'
  • 'floating'
maxWheelWidth Number, Array undefined Maximum width of the scroller wheels in pixels.
If number, it is applied to all wheels, if an array, it is applied to each wheel separately.
minWheelWidth Number, Array 80 Minimum width of the scroller 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:

iOS: 55
Material: 80
Windows Phone: 88
placeholder String undefined Placeholder string for the generated input.
renderItem Function undefined

You can use the renderItem option to fully customize wheel items. It takes a function that has the item as parameter and it should return the markup for that item.

renderItem: function(item) {
    return `<div class="my-custom-class">
        <div class="my-item-title">${item.display}</div>
        <div class="my-item-description">${item.data.description}</div>
    </div>`;
}

The item parameter can have the following properties:

  • display: String - The text of the item.
  • value: Any - The value of the item.
  • isGroup: Boolean - For group headers this property will be true
  • data: Any - The original option item that is passed in the data array

When the group wheel is also shown using the showGroupWheel option, the data property and the isGroup property of the item will be undefined in the case of the group wheel items. So, you can distinguish from the group wheel and the option wheel by checking if both the data and the isGroup are undefined.

responsive Object undefined Specify different settings for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the settings for the given breakpoint.
The available width is queried from the container element of the component and not the browsers viewport like in css media queries
There are five predefined breakpoints:
  • xsmall - min-width: 0px
  • small - min-width: 576px
  • medium - min-width: 768px
  • large - min-width: 992px
  • xlarge - min-width: 1200px
Custom breakpoints can be defined by passing an object containing the breakpoint property specifying the min-width in pixels. Example:
responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}
rows Number 3 Number of visible rows on the wheel. The default value depends on the theme:

iOS: 5
Material: 3
Windows: 6
scrollLock Boolean true Disables page scrolling on touchmove (if not in inline mode, and popup height is less than window height).
selectMultiple Boolean false If true, multiple selection will be enabled.
showArrow Boolean true Show or hide the popup arrow, when display mode is 'anchored'.
showGroupWheel Boolean false

If true and the select has groups, two wheels are shown. The first contains the group labels, and the second one the options.

Groups can be specified either by optgroup elements or by using the group property of the data items, when the data option is used.

Check out the grouping data section to learn how to group data or the data binding section for more details on how to pass data to the Select component.

showInput Boolean true If true, it will render an input field for the component.
showOnClick Boolean true Opens the component on element click/tap.
showOnFocus Boolean false - on desktop true - on mobile Pops up the component on element focus.
showOverlay Boolean true Show or hide overlay.
tags Boolean false If true and used with multiple date selection, it will display multiple values as "chips/tags".
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 custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'windows' - Windows theme
It's possible to modify theme colors or create custom themes.
Make sure that the theme you set is included in the downloaded package.
themeVariant String undefined

Controls which variant of the theme will be used (light or dark).

Possible values:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' or undefined - Detect the preferred system theme on devices where this is supported.

To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with '-dark', e.g.: 'my-theme' and 'my-theme-dark'.

touchUi Boolean, String 'auto'

Use true to render a touch optimized user interface, or false for a user interface optimized for pointer devices (mouse, touchpad).

Can be used with the responsive option to change the user interface based on viewport width.

If set to 'auto', the touch UI will be automatically enabled based on the platform.

wheelWidth Number, Array undefined Width of the scroller 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.
width Number, String undefined Sets the width of the popup container. This will take no effect in inline display mode.

Events

Name Description
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) Triggered when the value is changed.

Parameters

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

Example

$('#mobiscroll').mobiscroll().select({
    onChange: 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. Filtering can be turned on with the filter option.

To fully customize the filtering, the default filter behavior can be prevented by returning false from the handler function. To learn more about the filtering check out the Filtering Section above.

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) {
    }
});
onOpen(event, inst) Triggered when the component is opened.

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({
    onOpen: function (event, inst) {
    }
});
onPosition(event, inst) Triggered when the component is positioned (on initial show and resize / orientation change).
Useful if dimensions needs to be modified before the positioning happens, e.g. set a custom width or height. Custom positioning can also be implemented here, in this case, returning false from the handler function will prevent the built in positioning.

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) {
    }
});
onTempChange(event, inst) Triggered when the temporary value is changed.

Parameters

  • event: Object - The event object has the following properties:
    • value: String, Date, Moment.js Object or Array of String, Date, Moment.js object - The selected value.
  • inst: Object - The instance object of the select.

Methods

Name Description
close() Closes the component.

Example

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

// With instance
mobiscrollInstance.close();
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();
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();
getTempVal()

Returns the temporary value that's selected on the picker.

Depending on how the picker is displayed, the selection might be in a temporary state that hasn't been set yet. This temporary value can be aquired calling the getTempVal method on the picker instance.

The value that has been set to the input can be aquired using the getVal() method.

getVal() Returns the selected value of the picker, that has been set to the input as well.

Depending on how the picker is displayed, the selection might be in a temporary state that hasn't been set yet. This temporary value can be aquired calling the getTempVal method on the picker instance.

Returns: String, Number, Object or Array of String, Number or Object

The return value will be a single value or an array of values depending on the multiple option.

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();
open() Opens the component.

Example

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

// With instance
mobiscrollInstance.open();
position() Recalculates the position of the component (if not inline).

Example

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

// With instance
mobiscrollInstance.position();
reloadOptionElements()

Reloads the option elements from the DOM, when the select component is initialized on a select HTML element.

When changing the option elements dynamically in the DOM, this method should be called after the change, so the select is updated properly with the new data.

If you want to load or change the option dynamically, check out all data bining options.

Example

Methods can be called on an instance. For more details see calling methods
<select id="my-select-id">
    <option value="atlanta">Atlanta</option>
    <option value="new_york">New York</option>
</select>
const selectElement = $('#my-select-id');
// initialize the select first
const selectInstance = selectElement.mobiscroll().select({ theme: 'ios' }).mobiscroll('getInst');
// add an option dynamically
selectElement.append('<option value="boston">Boston</option>');
// reload the options from the DOM
selectInstance.reloadOptionElements(); // makes the 'Boston' appear on the select.
setOptions(options) Update 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('setOptions', {
    display: 'bottom'
});

// With instancee
mobiscrollInstance.setOptions({
    display: 'bottom'
});
setTempVal(value)

Sets the temporary value that's selected on the picker.

Depending on how the picker is displayed, the selection shown might be just a temporary value until the users hit the "Set" button to commit the selection. This temporary value can be adjusted calling the setTempVal method on the picker instance.

To get the current temporary value, check out the getTempVal instance method.

setVal(value) Sets the picker value and also writes it to the input.

Depending on how the picker is displayed, the selection shown might be just a temporary value until the users hit the "Set" button to commit the selection. This temporary value can be adjusted calling the setTempVal method on the picker instance.

To get the current selected value, check out the getVal instance method.

Parameters

  • value: String, Number, Object or Array of String, Number or Object - the value to set to the picker

The value should be a single value or an array of values depending on the multiple option.

The value set, should be part of the selection data. Please check out how selection data can be passed to the select!

Localization

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button.
filterEmptyText String 'No results'

Text for the empty state of the select wheels. The select will show this message, when the filtering is turned on and there are no results for the searched text.

filterPlaceholderText String 'Search'

Text for the select filter input placeholder. The filtering can be turned on with the filter option.

headerText Boolean, String '{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.
locale Object undefined Sets the language of the component. The locale option is an object containing all the translations for a given language. Mobiscroll supports a number of languages listed below. If a language is missing from the list, it can also be provided by the user. Here's a guide on how to write language modules.
Supported languages:
  • Arabic: localeAr, 'ar'
  • Bulgarian: localeBg, 'bg'
  • Catalan: localeCa, 'ca'
  • Czech: localeCs, 'cs'
  • Chinese: localeZh, 'zh'
  • Croatian: localeHr, 'hr'
  • Danish: localeDa, 'da'
  • Dutch: localeNl, 'nl'
  • English: localeEn or undefined, 'en'
  • English (UK): localeEnGB, 'en-GB'
  • Farsi: localeFa, 'fa'
  • German: localeDe, 'de'
  • Greek: localeEl, 'el'
  • Spanish: localeEs, 'es'
  • Finnish: localeFi, 'fi'
  • French: localeFr, 'fr'
  • Hebrew: localeHe, 'he'
  • Hindi: localeHi, 'hi'
  • Hungarian: localeHu, 'hu'
  • Italian: localeIt, 'it'
  • Japanese: localeJa, 'ja'
  • Korean: localeKo, 'ko'
  • Lithuanian: localeLt, 'lt'
  • Norwegian: localeNo, 'no'
  • Polish: localePl, 'pl'
  • Portuguese (Brazilian): localePtBR, 'pt-BR'
  • Portuguese (European): localePtPT, 'pt-PT'
  • Romanian: localeRo, 'ro'
  • Russian: localeRu, 'ru'
  • Russian (UA): localeRuUA, 'ru-UA'
  • Slovak: localeSk, 'sk'
  • Serbian: localeSr, 'sr'
  • Swedish:localeSv, 'sv'
  • Thai: localeTh, 'th'
  • Turkish: localeTr, 'tr'
  • Ukrainian: localeUa, 'ua'
  • Vietnamese: localeVi, 'vi'
$('#myexample').mobiscroll().select({
  locale: mobiscroll.localeDe
});

In some cases it's more convenient to set the locale using the language code string. You can do that by using the locale object, which contains all translations by language codes as keys.

The locale object is not tree-shakeable, meaning that all translations present in the object will end up in the application bundle, whether it's being used or not.
$('#myexample').mobiscroll().select({
  locale: mobiscroll.locale['de']
});
rtl Boolean false Right to left display.
setText String 'Set' Text for Set button.

Customizing the appearance

While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:

Override the Sass Color Variables

A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.

Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well, while still using platform specific themes (e.g. ios on iOS devices, material on Android devices, and mobiscroll on desktop). You can override the accent color for every theme:

$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;

@import "~@mobiscroll/JQuery/dist/css/mobiscroll.jquery.scss"
It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.
Here's a complete guide on how to set up Mobiscroll with SASS support

You can also customize the colors on many levels:

  1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
  2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
  3. Component and theme specific variables (ex. $mbsc-ios-dark-form-background, $mbsc-material-input-text) are applied to a specific theme and a specific component.

Tree Shaking for styles

Tree shaking is a term commonly used in web development and particularly in JavaScript for unused code removal. Since websites are served (mostly) over the network, loading times depend on content size, so minification and unused content elimination plays a major role in making webapps fluid.

For the JavaScript part, popular frameworks already have the treeshaking built in, so the components that are not used will be left out from the built project.

Eliminating unused styles

In case of the styles, leaving out the unused rules is not as straight forward.
The overarching idea is that CSS selectors match elements in the DOM, and those elements in the DOM come from all sorts of places: your static templates, dynamic templates based on server-side state, and of course, JavaScript, which can manipulate the DOM in any way at all, including pull things from APIs and third parties.

Sass variables to the rescue

The Mobiscroll Library comes with a modular SASS bundle, that can be configured which component styles and which themes to leave in and out for the compiled css file.

Every component and theme has a SASS variable that can be turned on or off. If the variable is falsy the styles that it needs will not be added to the bundle.

Example on configuring the styles
// include the ios theme
$mbsc-ios-theme: true;

// include the components:
$mbsc-datepicker: true;
$mbsc-eventcalendar: true;
        
@import "@mobiscroll/jquery/dist/css/mobiscroll.modular.scss"

In the above example the styles needed for the eventcalendar and datepicker will be included and only for the ios theme. All other components (like select or grid-layout) and all other themes will be left out from the bundle.

It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.

Here's the complete list of the components and themes that can be used:

Some components use others internally, so it might happen that even though you don't want to include some styles, they will still end up in your bundle.
For example if you don't want to include the form components (input, button, segmented, etc...), but you are using the select component, the styles for the mobiscroll buttons, will still be in, because of the dependency.

Accessibility

Keyboard Support

When focusing the input component rendered one can open the select using the Space or Enter keys.

The Tab and Shift + Tab keys can be used for navigating between the rendered wheels if there are multiple wheel available (for example having a group wheel). Also if there is a filter input or there are buttons rendered, the same keys will cycle through them too.

The Up and Down arrow keys can be used to focus wheelitems in desktop mode with the Space key to select the item. In mobile mode the arrow keys rotate the wheel so that automatically changes the selection.

The Enter key can be used to confirm the selection and close the picker, while the Esc key will act as a cancel action (also closing the select component).