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:

Template
<mbsc-select [(ngModel)]="country" [data]="countries" label="Pick Country"></mbsc-select>
Component
@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 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.

Number values example
<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},
        ];
    }
}
Object values example
<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.

Using with an input
<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.

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

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.

The select component with ngFor
<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.

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

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
<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[] = [];
}

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

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.
  • 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: (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
For a more detailed guide and examples on how to use the data option, check out the Data binding section.
Example for data array:
const strData = ['Paris', 'New York']; // string data
const objData = [ // object data
    {
        text: 'Paris',
        value: 1,
    },
    {
        text: 'New York',
        value: 2,
    }
]

disabled Boolean false Initial disabled state of the component.
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.
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.
invalid Array undefined An array of values that are invalid. Invalid options cannot be selected, and show up as disabled on the select wheels.
isOpen Boolean undefined Specifies wether the popup is opened or not. Use it together with the onClose event, by setting it to false when the popup closes.
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.
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.
maxWidth Number, String 600 Sets the maximum width of the component.
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
minWidth Number, String undefined Sets the maximum width of the component.
placeholder String undefined Placeholder string for the generated input.
responsive Object undefined Specify different settings for different viewport 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.

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

Using arrow functions is recommended so you have access to your outer component instance inside event handlers through this reference.
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

export class MyExample {
    settings: any = {
        onCancel: (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

export class MyExample {
    settings: any = {
        onChange: (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

export class MyExample {
    settings: any = {
        onClose: (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

export class MyExample {
    settings: any = {
        onDestroy: (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

export class MyExample {
    settings: any = {
        onInit: (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

export class MyExample {
    settings: any = {
        onOpen: (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

export class MyExample {
    settings: any = {
        onPosition: (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
mobiscrollInstance.close();
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 model can be aquired using the getVal() method.

The getTempVal and getVal methods are usually for advanced use-cases, when the built in options and the model bindings are not sufficient to work with.
getVal() Returns the selected value of the picker, that has been set to the model 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.

The getTempVal and getVal methods are usually for advanced use-cases, when the built in options and the model bindings are not sufficient to work with.
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
mobiscrollInstance.isVisible();
open() Opens the component.

Example

Methods can be called on an instance. For more details see calling methods
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
mobiscrollInstance.position();
reloadOptionElements()

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

When using the [mbsc-select] directive on a native select HTML element, the [mbsc-select-option] directive can also be used on the option elements. When doing so, the select will reload the option elements automatically without calling this method.

When the <mbsc-select> component is used with the <mbsc-select-option> components as children, the reloading is also done automatically without the need to call the reloadOptionElements() method.

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

The setTempVal and setVal methods are usually for advanced use-cases, when the built in options and the model bindings are not sufficient to work with.
setVal(value) Sets the picker value and also writes it to the model.

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!
The setTempVal and setVal methods are usually for advanced use-cases, when the built in options and the model bindings are not sufficient to work with.

Localization

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button.
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
  • Bulgarian: localeBg
  • Catalan: localeCa
  • Czech: localeCs
  • Chinese: localeZh
  • Croatian: localeHr
  • Danish: localeDa
  • Dutch: localeNl
  • English: localeEn or undefined
  • English (UK): localeEnGB
  • Farsi: localeFa
  • German: localeDe
  • Greek: localeEl
  • Spanish: localeEs
  • Finnish: localeFi
  • French: localeFr
  • Hebrew: localeHe
  • Hindi: localeHi
  • Hungarian: localeHu
  • Italian: localeIt
  • Japanese: localeJa
  • Korean: localeKo
  • Lithuanian: localeLt
  • Norwegian: localeNo
  • Polish: localePl
  • Portuguese (Brazilian): localePtBR
  • Portuguese (European): localePtPT
  • Romanian: localeRo
  • Russian: localeRu
  • Russian (UA): localeRuUA
  • Slovak: localeSk
  • Serbian: localeSr
  • Thai: localeTh
  • Swedish:localeSv
  • Turkish: localeTr
  • Ukrainian: localeUa
  • Vietnamese: localeVi
import { localeDe } from '@mobiscroll/angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
    myLocale = localeDe;
}
<mbsc-eventcalendar [locale]="myLocale"></mbsc-eventcalendar>
rtl Boolean false Right to left display.
selectedPluralText String '{count} selected' Specifies the plural form of the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items.
selectedText String '{count} selected' Specifies the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items.
setText String 'Set' Text for Set button.

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

Hereinafter you will see all the variables that are specific to the Select component or affect its look: