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:

<select id="my-select">
  <option value="USA">United State of America</option>
  <option value="CAN">Canada</option>
  <option value="MEX">Mexico</option>
</select>

$(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 and a value 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.

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.

<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
        },
    });
})

<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
        },
    });
})

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.

<label>Gender
    <select id="gender">
        <option value="female">Female</option>
        <option value="male">Male</option>
    </select>
</label>

$('#gender').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

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.

$('#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.

$('#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:

• Modal display modes
• "Live" selection

Modal display

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',
});

Options

buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]

buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]

const strData = ['Paris', 'New York']; // string data
            const objData = [ // object data
                {
                    text: 'Paris',
                    value: 1,
                },
                {
                    text: 'New York',
                    value: 2,
                }
            ]

responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}

Events

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

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

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

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

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

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

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

Methods

// With selector
$('#mobiscroll').mobiscroll('close');

// With instance
mobiscrollInstance.close();

// With selector
$('#mobiscroll').mobiscroll('destroy');

// With instance
mobiscrollInstance.destroy();

// With selector
$('#mobiscroll').mobiscroll('getInst');

// With instance
mobiscrollInstance.getInst();

// With selector
$('#mobiscroll').mobiscroll('isVisible');

// With instance
mobiscrollInstance.isVisible();

// With selector
$('#mobiscroll').mobiscroll('open');

// With instance
mobiscrollInstance.open();

// With selector
$('#mobiscroll').mobiscroll('position');

// With instance
mobiscrollInstance.position();

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

// With selector
$('#mobiscroll').mobiscroll('setOptions', {
    display: 'bottom'
});

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

Localization

$('#myexample').mobiscroll().select({
  locale: mobiscroll.localeDe
});

$('#myexample').mobiscroll().select({
  locale: mobiscroll.locale['de']
});

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:

• Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
• Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
• Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.

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"

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.