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:

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:

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.

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" />
}

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:

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.

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

Invalid items

Invalid items are items that cannot be selected. They appear disabled on the wheels and when clicked, a selection will not happen.

Invalid items can be set using the invalid option or the data option. The invalid option takes an array of values and disables those values. When using the data option, each item can take a disables property, that disables that item.

function App() {
    // standard react magic...
    const [selectedExtra, setSelectedExtra] = React.useState();
    const selectedChange = (ev) => { setSelectedExtra(ev.value); };

    // the options to choose from
    const extras = React.useState([{ value: 'sug', text: 'Sugar'}, { value: 'hon', disabled: true, text: 'Honey'}, { value: 'cre', text: 'Cream' }]);
    const invalid = ['sug'];

    return <Select value={selectedExtra} onChange={selectedChange} data={extras} invalid={invalid} />
}

Display modes

The select component can operate in two ways from the display option's point of view:

• Modal display modes
• "Live" selection

Modal display

Here comes the center, top, bottom displays, and also the anchored display when the touchUi option is true.

In these display modes, the picker shows up as a modal picker. When open, the selected value is stored as a temporary value until the set button is pressed. At that point the picker is closed and the value is commited to the 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

Customizing the input

By default the Select component renders a Mobiscroll Input component to show the selected value. This input component gets the focus and click handler that will open the picker.

function (props) {
    const data = [{ value: 'lon', text: 'London'}, { value: 'par', text: 'Paris'}, { value: 'ber', text: 'Berlin'}];

    return <Select data={selectData} />
}

To customize this Input component, you can pass props to it using the inputProps option. Or you can change the rendered component using the inputComponent option.

function (props) {
    const data = [{ value: 'lon', text: 'London'}, { value: 'par', text: 'Paris'}, { value: 'ber', text: 'Berlin'}];

    const propsForInput = {
        className: 'my-custom-css-class1 my-custom-css-class2',
        placeholder: 'Click to select...'
    };

    return <Select data={selectData} inputProps={propsForInput} />
}

Options

buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]

buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]

const strData = ['Paris', 'New York']; // string data
            const objData = [ // object data
                {
                    text: 'Paris',
                    value: 1,
                },
                {
                    text: 'New York',
                    value: 2,
                }
            ]

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

Events

<mobiscroll.Select
    onCancel={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onChange={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onClose={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onDestroy={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onInit={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onOpen={function (event, inst) {
    }}
/>

<mobiscroll.Select
    onPosition={function (event, inst) {
    }}
/>

Methods

mobiscrollInstance.close();

mobiscrollInstance.isVisible();

mobiscrollInstance.open();

mobiscrollInstance.position();

Localization

import { Eventcalendar, localeDe } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={localeDe} />;
}

import { Eventcalendar, locale } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={locale['de']} />;
}

Customizing the appearance

While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:

• Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
• Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
• Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.

Override the Sass Color Variables

A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.

Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well, while still using platform specific themes (e.g. ios on iOS devices, material on Android devices, and mobiscroll on desktop). You can override the accent color for every theme:

$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;

@import "~@mobiscroll/React/dist/css/mobiscroll.react.scss"

You can also customize the colors on many levels:

1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
3. Component and theme specific variables (ex. $mbsc-ios-dark-form-background, $mbsc-material-input-text) are applied to a specific theme and a specific component.