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

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

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.

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.

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

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

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

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

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

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

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.

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

• 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

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.

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

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,
                    group: 'Europe'
                },
                {
                    text: 'New York',
                    value: 2,
                    group: 'America'
                }
            ]

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>`;
}

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({
    onFilter: 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.

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.

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

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

• $mbsc-datepicker
• $mbsc-eventcalendar
• $mbsc-forms
• $mbsc-grid-layout
• $mbsc-popup
• $mbsc-select

• $mbsc-ios-theme
• $mbsc-material-theme
• $mbsc-windows-theme

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