Skip to main content
Version: 5.28.0

Select API

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

Options​

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. 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 button object can have the following properties:

  • text: string - Text of the button.
  • handler: string | () => void - The handler function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Approve action.
    • 'cancel' - Dismiss the popup.
  • icon: string - Icon for the button.
  • cssClass: string - CSS class for the button.
  • disabled: boolean - The disabled state of the button.
  • keyCode: number | string | Array<number | string> - 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'.
Example for using predefined and custom buttons
buttons: [
  'set',
  {
    text: 'Custom',
    icon: 'checkmark',
    cssClass: 'my-btn',
    handler: function (event) {
      alert('Custom button clicked!');
    }
  },
  'cancel'
]
Example for using a predefined button handler
buttons: [
  '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

Specify the DOM element in which the component is rendered and positioned, if display is 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.

When it's an array of objects, the objects can have the following properties:

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

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

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

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

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

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​

missing

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

"dark" | "light" | "auto"

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​

@cancel​

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

@change​

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

@close​

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

@destroy​

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

Triggered when the component is destroyed.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

@filter​

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

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.

@init​

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

Triggered when the component is initialized.

Parameters:

  • args - The event argument object.

  • inst - The component instance.

@open​

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

@temp-change​

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

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'

locale​

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

getTempVal​

() => any

Returns the temporary value selected on the picker.

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.

Slots​

item​

<template #item="args">...</template>

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