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, a value and optionally a group 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.

The group property must be a string, that is used to group together a number of options. The options that have the same string specified by the group property will be grouped together. When groups are specified in the data, a header will be shown at the top of each group with the text specified in the group property. Additionally, when using the showGroupWheel option, an additional wheel will be shown, with the groups to help navigation.

Check out the Grouping section for more details.

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

Group options

Through the data option, with each select item can be passed an optional group property. This group property is a string, that defines the group of the item. When the group is passed to any of the items, the whole data is treated as grouped and a header will be rendered above each group on the select wheels. The header will contain the group name as specified in the group property.

var myCountries = [{
    text: 'United Kingdom',
    value: 'GB',
}, {
    text: 'France',
    value: 'FR',
    group: 'Europe'
}, {
    text: 'Hungary',
    value: 'HU',
    group: 'Europe'
}, {
    text: 'United States of America',
    value: 'US',
    group: 'America'
}];

<Select data={myCountries} />

Furthermore an additional "group wheel" can be also rendered with the showGroupWheel option set to true. The group wheel items will be the group property values or the optgroup label attributes, and will help in navigating the option wheel.

<Select data={myCountries} showGroupWheel={true} />

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

Filtering

Filtering can be turned on with the filter option. It is very usefull when using large datasets and you want to find a particular item.

When filtering is on, a filter input is rendered above the select options. The placeholder of the input can be customized and localized with the filterPlaceholderText option.
Typing a text in the input filters the options you can select from. Also, with each change on the filter input text, the onFilter event is triggered.

When no items match the filter the Mobiscroll Select will show a "No results" message, that can be customized and localized with the filterEmptyText option.

Remote Filtering

Server side filtering can be implemented by customizing the filtering. Returning false from the onFilter event handler function will prevent the filtering of the option items. A request can be made to the server with the filterText and the returned data can be set to the Mobiscroll Select dynamically.

function App() {
    // state for the selected value
    const [country, setSelectedCountry] = React.useState(null);
    // handler for the value change
    const selectedChange = (ev) => { setSelectedCountry(ev.value); };
    // the options to choose from
    const [countries, setCountries] = React.useState([]);

    const customFilter = (ev) => {
        const phrase = ev.filterText;

        // handle custom filtering here
        yourCustomFiltering(phrase, setCountries);

        return false; // return false to prevent default filtering
    }
    return <Select value={country} onChange={selectedChange} data={countries} onFilter={customFilter} />
}

function yourCustomFiltering(text, setData) {
    // get the filtered array from the server
    // ...
    setData(data);
}

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

Select Item Templating

The items can be customized using the renderItem and the itemHeight options.

The renderItem function will be used to render each item. An item parameter is passed to it, so you can access the item's data. The itemHeight option can be adjusted for styles that go beyond the default height.

function FlagRenderer(item) {
    return <div className="my-country-container">
        <img src={item.data.flagUrl} />
        {item.data.text}
    </div>;
}

function App() {
    const countries = React.useState([{
        value: 'US',
        text: 'United States of America',
        flagUrl: '//urlto/usa-flag',
    }, {
        value: 'DE',
        text: 'Germany',
        flagUrl: '//urlto/german-flag',
    }, {
        value: 'FR',
        text: 'France',
        flagUrl: '//urlto/french-flag',
    }]);

    return <Select data={countries} renderItem={FlagRenderer} itemHeight={56} />;
}

The item parameter has the following properties:

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

If the data contains groups, some of the items that are passed to the custom renderer function will be header items. In these cases, there will be no data property on the header items but there will be an isGroup property that will be true.

If the group wheel is also turned on with the showGroupWheel option, the items from the group wheel that are passed to the renderer function won't have neither the dataproperty nor the isGroup property on them.

data = [{
    text: 'User 1',
    value: 'username1',
    userID: 1,
    group: 'Admin'
}, {
    text: 'User 2',
    value: 'secondUser',
    userID: 2,
    group: 'Sales'
}, {
    text: 'User 3',
    value: 'thirdUser',
    userID: 3,
    group: 'Support'
}, {
    text: 'User 4',
    value: 'username4',
    userID: 4,
    group: 'Support'
}]

function renderItem(item) {
    if (!item.isGroup && !item.data) { // Group wheel item
        return <div className="group-wheel-item">{item.display}</div>;
    }
    if (item.isGroup) { // Option wheel - group header item
        return <div className="group-header-item">{item.display}</div>;
    }
    if (item.data) { // Option wheel - option item
        return <div className="option-item">
             <div className="title">{item.data.value}</div>
             <div className="description">#{item.data.userID} {item.data.text}</div>
        </div>;
    }
}

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,
                    group: 'Europe'
                },
                {
                    text: 'New York',
                    value: 2,
                    group: 'America'
                }
            ]

renderItem={(item) => {
    return <div className="my-custom-class">
        <div className="my-item-title">{item.display}</div>
        <div className="my-item-description">{item.data.description}</div>
    </div>;
}}

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
    onFilter={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.