Skip to main content
Version: 5.34.0

Select API

Here is a comprehensive list of all the options, events and methods of the Select component.

Options​

Explore the following API options that help you easily configure the Select.

anchor​

HTMLElement

Specifies the anchor element for positioning, if display is set to 'anchored'.

Default value: undefined

animation​

boolean | "pop" | "slide-down" | "slide-up"

Animation to use when the component is opened or closed, if display is not set to 'inline'. Possible values:

  • 'pop'
  • 'slide-down'
  • 'slide-up'

If false, the animation is turned off.

Default value: undefined

ariaLabel​

string

Specifies the accessible name of the picker input.

Default value: undefined

buttons​

Array<string | MbscPopupButton>

Buttons to display on the component. Each item of the array will be a button. A button can be specified as a string, or as a button object.

If a string, it must be one of the predefined buttons:

  • 'ok' - Approve action. Will display the caption specified by the okText option.
  • 'cancel' - Dismisses the popup. Will display the caption specified by the cancelText option.
  • 'close' - Closes the popup. Will display the caption specified by the closeText option.
  • 'set' - Approve action. Will display the caption specified by the setText option.

The MbscPopupButton type has the following properties:

  • color: "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" - Specifies the predefined color of the button
  • cssClass: string - A custom CSS class that will be applied to the element
  • disabled: boolean - Disabled state of the button
  • handler: MbscPopupPredefinedButton | (event: any) => void - Specifies what happens when the button is pressed. It can be a predefined button handler like 'set', 'cancel' or a custom function.
  • icon: string - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed.
  • keyCode: number | "enter" | "esc" | "space" | Array<number | "enter" | "esc" | "space"> - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: 'enter', 'esc', 'space'.
  • text: string - Sets the label of the button
  • variant: "outline" | "standard" | "flat" - The style of the button
Example for using predefined and custom buttons
[
  'set',
  {
    text: 'Custom',
    icon: 'checkmark',
    cssClass: 'my-btn',
    handler: function (event) {
      alert('Custom button clicked!');
    }
  },
  'cancel'
]
Example for using a predefined button handler
[
  'set',
  {
    text: 'Hide',
    handler: 'cancel',
    icon: 'close',
    cssClass: 'my-btn'
  }
]

Default value: ['set', 'cancel']

circular​

boolean | Array<boolean>

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 the displayed rows, the scroll wheel becomes circular.

Default value: undefined

closeOnEsc​

boolean

If true, the popup is closed when the ESC key is pressed.

Default value: true

closeOnOverlayClick​

boolean

If true, the popup is closed on overlay click or tap.

Default value: true

context​

string | HTMLElement

The DOM element in which the component is appended and positioned (when not inline). Can be a selector string or a DOM element.

Default value: 'body'

cssClass​

string

Specifies a custom CSS class for the component.

Default value: undefined

data​

Array<string | number | MbscSelectData>

Specifies the selectable options for the component.

When it's an array of strings, the selectable options will be the items of the array. The strings will appear on the picker, and the selected values will be the strings themselves.

The MbscSelectData type has the following properties:

  • disabled: boolean - The disabled state of the option. Disabled options cannot be selected.
  • group: string - The group name, in case of grouped options.
  • text: string - The label of the option
  • value: any - The value of the option

Default value: undefined

defaultSelection​

any

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

Default value: undefined

disabled​

boolean

Specifies the disabled state of the input.

Default value: false

display​

MbscPopupDisplay

Controls the positioning of the component. Possible values are:

  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - The component is rendered inline.
  • 'anchored' - The component appears positioned to the element defined by the anchor option.
  • '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.

Default value: undefined

dropdown​

boolean

If false, the down arrow icon is hidden.

Default value: true

endIcon​

string

Specifies the icon which will be displayed at the end of the input. Use the startIcon option for specifying an icon at the start.

Default value: undefined

error​

boolean

If true, the input will be displayed with error styles.

Default value: false

errorMessage​

string

Error message for the input. If the error option is set to true, the message will be displayed.

Default value: undefined

filter​

boolean

If true, it turns filtering on. A filter input will be rendered above the selectable options. Typing in the input will filter the selectable options and will also trigger the onFilter event.

The default behavior is based on the presence of the search term in the option text. The onFilter event can be used to prevent the default filtering and customize the experience.

Default value: false

focusOnClose​

boolean

If true, after closing the popup the focus will be moved to the last focused element before the popup was opened.

Default value: true

focusOnOpen​

boolean

If true, the popup will receive the focus when opened.

Default value: true

focusTrap​

boolean

If true and display is not set to 'inline', focus won't be allowed to leave the popup.

Default value: true

headerText​

string

Specifies a custom string which appears in the picker header. If it contains the '{value}' string, it will be replaced with the selected value of the picker.

Default value: undefined

inputComponent​

any

The input component to render if the picker is modal If not specified, it will render a Mobiscroll Input component.

Props can be specified using the inputProps option.

Default value: undefined

inputProps​

any

Props for the rendered input, specified by the inputComponent option.

Default value: undefined

inputStyle​

"outline" | "box" | "underline"

Specifies the style of the input. Possible values:

  • 'underline'
  • 'box'
  • 'outline'

The default value depends on the theme:

  • iOS: 'underline'
  • Material: 'box'
  • Windows: 'outline'

Default value: undefined

invalid​

Array<any>

An array of values that are invalid. Invalid options cannot be selected, and show up as disabled on the Select.

Default value: undefined

isOpen​

boolean

Specifies if the component is opened or not. Use it together with the onClose event, by setting it to false when the component closes.

Default value: false

itemHeight​

number

Height in pixels of one item on the wheel. The default value depends on the theme:

  • iOS: 34
  • Material: 40
  • Windows: 44

label​

string

Specifies the label of the input.

Default value: undefined

labelStyle​

"inline" | "floating" | "stacked"

Specifies the position of the input label. Possible values:

  • 'stacked'
  • 'inline'
  • 'floating'

The default value depends on the theme:

  • iOS: 'inline'
  • Material: 'floating'
  • Windows: 'stacked'

Default value: undefined

maxHeight​

string | number

Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px.

Default value: undefined

maxWheelWidth​

number | Array<number>

Maximum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately.

Default value: undefined

maxWidth​

string | number

Sets the maximum width of the component.

Default value: undefined

minWheelWidth​

number | Array<number>

Minimum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately.

Default value: undefined

responsive​

MbscResponsiveOptions<MbscSelectOptions>

Specifies different options 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 options for the given breakpoint.

info

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, you can use multiple, but each must have a unique name
    breakpoint: 600,
    display: 'center'
  },
  large: {
    display: 'anchored'
  }
}

Default value: undefined

rows​

number

Number of visible rows on the wheel. The default value depends on the theme:

  • iOS: 5
  • Material: 3
  • Windows: 6

selectMultiple​

boolean

If true, multiple selection will be enabled.

Default value: false

showArrow​

boolean

Show or hide the popup arrow, when display is 'anchored'.

Default value: true

showGroupWheel​

boolean

If true and the Select has groups, two columns will be rendered on the picker, the first containing the group labels, and the second one the options. Groups can be specified either by optgroup elements, when the data comes from the html markup, or by using the group property of the option objects, when the data option is used.

Default value: false

showInput​

boolean

If true, it will render an input field for the component.

Default value: true

showOnClick​

boolean

Opens the component on element click/tap.

Default value: true

showOnFocus​

boolean

Opens the component on element focus.

Default value: false on desktop, true on mobile

showOverlay​

boolean

Show or hide the popup overlay.

Default value: true

startIcon​

string

Specifies the icon which will be displayed at the start of the input. Use the endIcon option for specifying an icon at the end.

Default value: undefined

tagInput​

boolean

If true and used with multiple selection, it will display the selected values inside the input as tags (chips).

Default value: false

theme​

string

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

info

Make sure that the theme you set is included in the downloaded package.

Default value: undefined

themeVariant​

"auto" | "light" | "dark"

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

Default value: undefined

touchUi​

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

Default value: 'auto'

wheelWidth​

number | Array<number>

Width of the scroller wheels, in pixels. Wheel content will be truncated, if it exceeds the width. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately.

Default value: undefined

Events​

The Select component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code.

onCancel​

(args: MbscSelectCancelEvent, inst: SelectBase) => void

Triggered when the picker is canceled.

Parameters:

  • args - The event argument with the following properties:

    • value: any - The selected value.
    • valueText: string - The selected value as text.

  • inst - The component instance.

onChange​

(args: MbscSelectChangeEvent, inst: SelectBase) => void

Triggered when the value is changed.

Parameters:

  • args - The event argument with the following properties:

    • value: any - The selected value.
    • valueText: string - The selected value as text.

  • inst - The component instance.

onClose​

(args: MbscSelectCloseEvent, inst: SelectBase) => void

Triggered when the picker is closed.

Parameters:

  • args - The event argument with the following properties:

    • value: any - The selected value.
    • valueText: string - The selected value as text.

  • inst - The component instance.

onDestroy​

(args: any, inst: any) => void

Triggered when the component is destroyed.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

onFilter​

(args: MbscSelectFilterEvent, inst: SelectBase) => boolean | void

Triggered when the value of the filter input changes. Filtering can be turned on with the filter option.

To fully customize the filtering, the default behavior can be prevented by returning false from the handler function.

Parameters:

  • args - The event argument with the following properties:

    • filterText: string - The value of the filter input.

  • inst - The component instance.

onInit​

(args: any, inst: any) => void

Triggered when the component is initialized.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

onOpen​

(args: MbscSelectOpenEvent, inst: SelectBase) => void

Triggered when the picker is opened.

Parameters:

  • args - The event argument with the following properties:

    • target: HTMLElement - The DOM element of the popup.
    • value: any - The selected value.
    • valueText: string - The selected value as text.

  • inst - The component instance.

onTempChange​

(args: MbscSelectTempChangeEvent, inst: SelectBase) => void

Triggered when the temporary value is changed.

Parameters:

  • args - The event argument with the following properties:

    • value: any - The selected value.

  • inst - The component instance.

Localization​

The Select component is fully localized. This covers date and time format, button copy, rtl and more.

cancelText​

string

Text for the "Cancel" button.

Default value: 'Cancel'

closeText​

string

Text for the "Close" button.

Default value: 'Close'

filterEmptyText​

string

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

Default value: 'No results'

filterPlaceholderText​

string

Placeholder text for the filter input, when filtering is turned on.

Default value: 'Search'

groupText​

string

Specifies the accessibility label for the group wheel, when present.

Default value: 'Group'

locale​

MbscLocale

Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a custom language module.

Supported values:

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

Default value: undefined

okText​

string

Text for the "Ok" button.

Default value: 'Ok'

rtl​

boolean

Enables right-to-left display.

Default value: false

setText​

string

Text for the "Set" button.

Default value: 'Set'

Methods​

These methods are actions that can be performed on a component instance.

close​

() => void

Closes the component.

getTempVal​

() => any

Returns the temporary value selected on the picker.

getVal​

() => any

Returns the selected value of the picker.

isVisible​

() => boolean

Returns a boolean indicating whether the component is visible or not.

open​

() => void

Opens the component.

position​

() => void

Recalculates the position of the component (if not inline).

reloadOptionElements​

() => void

Reloads option elements from the DOM, when the Select component is initialized on a html select 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.

setOptions​

(opt: MbscSelectOptions) => void

Sets or updates options of the component. Options can be updated dynamically after the initialization.

It receives an options object as parameter. Calling setOptions will overwrite all the options that have a key in the options object parameter, and it will re-render the component.

inst.setOptions({
  themeVarian: 'dark',
})

setTempVal​

(value: any) => void

Sets the temporary value to be selected on the picker. The value will be committed when the user hits the set button.

Parameters:

  • value - The value to set.

setVal​

(value: any) => void

Sets the picker value and also writes it to the input.

Parameters:

  • value - The value to set.

Renderers​

The display of the Select component can be customized with different render functions.

renderItem​

(args: MbscSelectItemData) => any

Customize each selectable item on the wheel.

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.

Available parameters:

  • 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: MbscSelectData - The original option item that is passed in the data array

Default value: undefined

Types​

MbscLocale​

Interface

Properties:

  • allDayText: string
  • amText: string
  • calendarSystem: MbscCalendarSystem
  • cancelText: string
  • clearText: string
  • closeText: string
  • dateFormat: string
  • dateFormatFull: string
  • dateFormatLong: string
  • dateText: string
  • dateWheelFormat: string
  • dayNames: Array<string>
  • dayNamesMin: Array<string>
  • dayNamesShort: Array<string>
  • daySuffix: string
  • dayText: string
  • eventText: string
  • eventsText: string
  • filterEmptyText: string
  • filterPlaceholderText: string
  • firstDay: number
  • fromText: string
  • hourText: string
  • minuteText: string
  • monthNames: Array<string>
  • monthNamesShort: Array<string>
  • monthSuffix: string
  • monthText: string
  • moreEventsPluralText: string
  • moreEventsText: string
  • nextMonthText: string
  • nextYearText: string
  • noEventsText: string
  • nowText: string
  • pmText: string
  • prevMonthText: string
  • prevYearText: string
  • rangeEndHelp: string
  • rangeEndLabel: string
  • rangeStartHelp: string
  • rangeStartLabel: string
  • rtl: boolean
  • secondText: string
  • selectedPluralText: string
  • selectedText: string
  • setText: string
  • timeFormat: string
  • timeText: string
  • timeWheels: string
  • toText: string
  • todayText: string
  • weekText: string
  • yearSuffix: string
  • yearText: string

MbscPopupButton​

Interface

Properties:

  • color: "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" - Specifies the predefined color of the button
  • cssClass: string - A custom CSS class that will be applied to the element
  • disabled: boolean - Disabled state of the button
  • handler: MbscPopupPredefinedButton | (event: any) => void - Specifies what happens when the button is pressed. It can be a predefined button handler like 'set', 'cancel' or a custom function.
  • icon: string - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed.
  • keyCode: number | "enter" | "esc" | "space" | Array<number | "enter" | "esc" | "space"> - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: 'enter', 'esc', 'space'.
  • text: string - Sets the label of the button
  • variant: "outline" | "standard" | "flat" - The style of the button

MbscPopupDisplay​

"center" | "bottom" | "top" | "anchored" | "inline" | "bubble"

MbscPopupPredefinedButton​

"set" | "cancel" | "ok" | "close"

MbscResponsiveOptions<MbscSelectOptions>​

Interface

The MbscResponsiveOptions<MbscSelectOptions> supports custom properties in the form:

[key:string]: MbscSelectOptions & {breakpoint?: number}

The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The breakpoint property, when present, specifies the min-width in pixels. The options will take into effect from that width.

info

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

MbscSelectData​

Interface

Properties:

  • disabled: boolean - The disabled state of the option. Disabled options cannot be selected.
  • group: string - The group name, in case of grouped options.
  • text: string - The label of the option
  • value: any - The value of the option

The MbscSelectData supports custom properties in the form:

[key:string]: any

The data object is available in the templates, so it is a convenient way for customizing the items on the select.

Example:

{
  value: 'US',
  text: 'United States of America',
  flagUrl: '//urlto/usa-flag', // custom property
}, {
  value: 'DE',
  text: 'Germany',
  flagUrl: '//urlto/german-flag',
}