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:

<mbsc-select [(ngModel)]="country" [data]="countries" label="Pick Country"></mbsc-select>

@Component({...})
export class MyApp implements OnInit {
    public countries: string[];
    public country: string;
    ngOnInit() {
        this.countries = [
          { value: 'USA', text: 'United State of America' },
          { value: 'CAN', text: 'Canada' },
          { value: 'MEX', text: 'Mexico' }];
    }
}

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.

<mbsc-select [(ngModel)]="departmentID" [data]="departments" label="Pick Department"></mbsc-select>

@Component({...})
export class MyApp implements OnInit {
    public departments: any[];
    public departmentID: number;
    ngOnInit() {
        this.departments = [
            { text: 'Sales', value: 1 },
            { text: 'Support', value: 2},
            { text: 'Development', value: 3},
        ];
    }
}

<mbsc-select [(ngModel)]="selectedUser" [data]="users" label="Select a user"></mbsc-select>

interface IUser {
    id: number;
    fullName: string;
};

@Component({...})
export class MyApp implements OnInit {
    public users: Array<{ text: string; value: IUser; }>
    public selectedUser: IUser;
    ngOnInit() {
        this.users = [
            { text: 'Alice', value: { id: 123, fullName: 'Alice Cooper' }},
            { text: 'Brandon', value: { id: 456, fullName: 'Brandon Lee' }},
            { text: 'Louisa', value: { id: 789, fullName: 'Louisa Crawford'}},
        ];
    }
}

Data through templates

Just like the native <select> element has <option> elements as children, that define selection options, the Mobiscroll Select component has <mbsc-select-option> components.

This can come in handy, when there are only a few number of options that are always the same to choose from.

<mbsc-select [(ngModel)]="gender" label="Gender">
    <mbsc-select-option value="female">Female</mbsc-select-option>
    <mbsc-select-option value="male">Male</mbsc-select-option>
</mbsc-select>

Native elements

The Mobiscroll Select can also be used as a directive. This can be usefull when using the select with custom components, or custom styled native elements.

The select directive can be used on native elements: <input /> or <select>.

When using the select directive on an <input />, the data option must be provided.

<label>My Input
    <input [(ngModel)]="selected" mbsc-select [data]="selectData" />
</label>

When using the select directive with <select> elements, the options will be read from the <option> elements.

<label>My Select
    <select [(ngModel)]="gender" mbsc-select>
        <option value="female">Female</option>
        <option value="male">Male</option>
    </select>
</label>

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.

public 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'
}];

<mbsc-select [data]="myCountries"></mbsc-select>

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

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.

<mbsc-select [data]="myCountries" [showGroupWheel]="true"></mbsc-select>

Working with Ionic

The Mobiscroll Select can be used as a directive. This can be usefull when using the select with custom components, or custom styled native elements.

Ionic is a good example for custom components usage. For instance, the select directive can be used on an <ion-input> component, thus one can have the selection handled by the select and at the same time maintain the style of an ionic form.

<ion-item>
    <ion-label>My Label</ion-label>
    <ion-input [(ngModel)]="selected" mbsc-select [data]="selectData"></ion-input>
</ion-item>

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.

Data binding

When using the [data] binding for passing the data to the select passing a different array will work out of the box and update the selection options.

public myData: string[] = [];

ngOnInit() {
    this.myData = ['Alice', 'In', 'Wonderland'];
}

<mbsc-select [data]="myData" [(ngModel)]="selected"></mbsc-select>

Data from template

When using the template to get the data from, an *ngFor directive can also be used to generate the options.

<mbsc-select [(ngModel)]="selected">
    <mbsc-select-option *ngFor="var item of items" [value]="item">{{item}}</mbsc-select-option>
</mbsc-select>

When working with dynamically generated native option elements, the mbsc-select-option directive can be used on them, to let the select know about the data changes.

<select [(ngModel)]="selected" mbsc-select>
    <option mbsc-select-option *ngFor="var item of items" [value]="item">{{item}}</option>
</select>

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.

<mbsc-select [(ngModel)]="selectedCountry" [data]="countries" [options]="selectOptions"></mbsc-select>

@Component(...)
export class MyComponent {
    public countries = [];
    public selectedCountry: string;
    public selectOptions: MbscSelectOptions = {
        filter: true,
        onFilter: (event: any) => {
            this.yourCustomFilter(event.filterText); // handle custom filtering
            return false; // return false to prevent default filtering
        }
    };

    private yourCustomFilter(phrase) {
        // your custom filtering implementation here
        // ...
        this.countries = 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.

<mbsc-select [selectMultiple]="true" [(ngModel)]="selectedBonuses" [data]="bonuses"></mbsc-select>

@Component(...)
export class MyComponent {
    public bonuses = ['Free ticket', 'Free Drink', 'Free Hug'];
    public selectedBonuses: string[] = [];
}

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.

<mbsc-select [(ngModel)]="selectedExtra" [data]="extras" [invalid]="myInvalid"></mbsc-select>

@Component(...)
export class MyComponent {
    public extras = [{ value: 'sug', text: 'Sugar'}, { value: 'hon', disabled: true, text: 'Honey'}, { value: 'cre', text: 'Cream' }];
    public myInvalid = ['sug'];
    public selectedExtra: string;
}

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

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.

"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 model

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" mbsc-select>
    <option value="lon">London</option>
    <option value="ber">Berlin</option>
    <option value="par">Paris</option>
</select>

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. This option will only work with the directive version of the component.

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

<select id="my-select" mbsc-select [inputElement]="myInput">
    <option value="lon">London</option>
    <option value="ber">Berlin</option>
    <option value="par">Paris</option>
</select>

Select Item Templating

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

The template will be used to render each item. An item parameter is also 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.

countries = [{
    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',
}];

<mbsc-select [itemTemplate]="flagTemplate" [itemHeight]="56" [(ngModel)]="selected" [data]="countries">
    <ng-template #flagTemplate let-item>
        <div class="my-country-container">
            <img [src]="item.data.flagUrl" />
            {{item.data.text}}
        </div>
    </ng-template>
</mbsc-select>

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 template 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 template 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'
}]

<ng-template #userTemplate let-item>
    <div *ngIf="!item.isGroup && !item.data"> <!-- Group wheel item -->
        <div class="group-wheel-item">{{item.display}}</div>
    </div>
    <div *ngIf="item.isGroup"> <!-- Option wheel - group header item -->
        <div class="group-header-item">{{item.display}}</div>
    </div>
    <div *ngIf="item.data">
        <div class="option-item">
            <div class="title">{{item.data.value}}</div>
            <div class="description">#{item.data.userID} {{item.data.text}}</div>
        </div>
    </div>
</ng-template>

Options

buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: (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'
                }
            ]

<mbsc-select [itemTemplate]="myCustomTemplate" [data]="myData">
    <ng-template #myCustomTemplate let-item>
        <div class="my-custom-class">
            <div class="my-item-title">${item.display}</div>
            <div class="my-item-description">${item.data.description}</div>
        </div>
    </ng-template>
</mbsc-select>

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

Events

export class MyExample {
    settings: any = {
        onCancel: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onChange: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onClose: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onDestroy: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onFilter: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onInit: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onOpen: (event, inst) => {
        }
    }
}

export class MyExample {
    settings: any = {
        onPosition: (event, inst) => {
        }
    }
}

Methods

mobiscrollInstance.close();

mobiscrollInstance.isVisible();

mobiscrollInstance.open();

mobiscrollInstance.position();

<select mbsc-select [(ngModel)]="selectedCity">
    <option *ngFor="let city of cities" [value]="city.value" mbsc-select-option>{{city.name}}</option>
</select>

Localization

import { localeDe } from '@mobiscroll/angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
    myLocale = localeDe;
}

<mbsc-eventcalendar [locale]="myLocale"></mbsc-eventcalendar>

import { locale } from '@mobiscroll/angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
    myLocale = locale['de'];
}

<mbsc-eventcalendar [locale]="myLocale"></mbsc-eventcalendar>

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/Angular/dist/css/mobiscroll.angular.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/angular/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).