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:

JSX
import { Select } from '@mobiscroll/react';

function App() {
    const countries = [
          { value: 'USA', text: 'United State of America' },
          { value: 'CAN', text: 'Canada' },
          { value: 'MEX', text: 'Mexico' }];
    return <Select data={countries} label="Pick Country" />
}

To use the Mobisroll Select as a controlled component, you can pass a value and an onChange handler to handle the state changes like this:

JSX
import { Select } from '@mobiscroll/react';

function ControlledComponentExample() {
    // the options to choose from
    const countries = ['USA', 'Canada', 'Mexico'];

    // the state to store the selection
    const [country, setCountry] = React.useState(null);

    // handler for the selection change
    const countrySelected = (ev) => {
        setCountry(ev.value);
    }

    return <Select value={country} onChange={countrySelected} data={countries} label="Pick Country" />
}

Data binding

The Mobiscroll Select component has a data option (or data prop), that is used to define the selection options.

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
import { Select } from '@mobiscroll/react';

function App() {
    // array containing the data options (department ID's in this example)
    const departmentData = [
        { text: 'Sales', value: 1 },
        { text: 'Support', value: 2},
        { text: 'Development', value: 3},
    ];
    // state for storing the selected id
    const [departmentID, setDepartmentID] = React.useState(null);
    // handler for the selection
    const departmentChange = (ev) => {
        setDepartmentID(ev.value);
    }

    return <Select data={departmentData} label="Select department" />
}
Object values example
import { Select } from '@mobiscroll/react';

function App() {
    // array containing the data options (user objects in this example)
    const usersData = [
        { text: 'Alice', value: { id: 123, fullName: 'Alice Cooper' }},
        { text: 'Brandon', value: { id: 456, fullName: 'Brandon Lee' }},
        { text: 'Louisa', value: { id: 789, fullName: 'Louisa Crawford'}},
    ];
    // state for the selected user
    const [user, setUser] = React.useState(null);
    // selection handler
    const userSelected = (ev) => {
        setUser(ev.value);
    }

    return <Select data={usersData} value={user} onChange={userSelected} label="Select user" />
}

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.

To notify the select component of the change of data, you only have to pass a different array. This can be achieve in multiple ways, but using a simple spread operator is one of the easiest. Also using a state variable and calling its setter when the data becomes available is a best practice. Check out the example below:

Loading options from an API
import { Select } from '@mobiscroll/react';

function App() {
    const [data, setData] = React.useState([]); // the initial array contains nothing
    // state for the selected item
    const [selected, setSelected] = React.useState(null);
    // selection handler
    const onSelected = (ev) => {
        setSelected(ev.value);
    };

    React.useEffect(() => {
        myGetDataFromAPI() // fetch the data from a remote API
            .then((fetchedData) => {
                setData(fetchedData); // set the fetched data to the state
            });
    }, []);

    return <Select data={data} value={selected} onChange={onSelected} label="Select item" />
}

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
function App() {
    // state for the selected values
    const [selectedBonuses, setSelectedBonuses] = React.useState([]);
    // handler for the value change
    const selectedChange = (ev) => { setSelectedBonuses(ev.value); };
    // the options to choose from
    const bonuses = React.useState(['Free ticket', 'Free Drink', 'Free Hug']);

    return <Select selectMultiple={true} value={selectedBonuses} onChange={selectedChange} data={bonuses} />
}

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

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 state

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: function (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.
inputComponent Function, String undefined

The input component to render if the picker is modal (the display option is not set to 'inline').

The following values are supported:

  • 'input' - renders a standard HTML input.
  • IonInput - renders an IonInput in case of Ionic React.

If not specified, a mobiscroll Input will be rendered.

Props can be specified using the inputProps option.

inputProps Object undefined Props for the rendered input, specified by the inputComponent option.
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

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

<mobiscroll.Select
    onCancel={function (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

<mobiscroll.Select
    onChange={function (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

<mobiscroll.Select
    onClose={function (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

<mobiscroll.Select
    onDestroy={function (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

<mobiscroll.Select
    onInit={function (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

<mobiscroll.Select
    onOpen={function (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

<mobiscroll.Select
    onPosition={function (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();
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 state management tools of React are not sufficien 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();
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 state management tools of React are not sufficien 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 { Eventcalendar, localeDe } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={localeDe} />;
}
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/React/dist/css/mobiscroll.react.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: