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

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

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.

Assigning groups to items
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.

Rendering the group 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:

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

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.

Custom (remote) filtering example
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.

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

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.

Invalid example
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:

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.

Example for custom item rendering
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:

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.

Differentiating between wheels, option and header items
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

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
  • groupString - Specify the group name
  • disabledBoolean - Specify the item as disabled. Disabled items cannot be selected

For a more detailed guide and examples on how to use the data option, check out the Data binding section. If you want to learn more about organising the data into groups, please see the Grouping section

Example for data array:
const strData = ['Paris', 'New York']; // string data
            const objData = [ // object data
                {
                    text: 'Paris',
                    value: 1,
                    group: 'Europe'
                },
                {
                    text: 'New York',
                    value: 2,
                    group: 'America'
                }
            ]

defaultSelection Any undefined

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

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.
filter Boolean false

It turns filtering on, when true. When filtering is on, a filter input will be shown above the wheels. Typing in the input will filter the select data and will also trigger the onFilter event.

The default behavior is based on the presence of the search phrase in the option labels. The onFilter event can be used to prevent the default filtering and customize the experience. Check out the Filtering Section for more use case examples.

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.
inputStyle String 'underline' Defines the input rendering mode. By default the input has the underline styling. Possible values:
  • 'underline'
  • 'box'
  • 'outline'
invalid Array undefined An array of values that are invalid. Invalid options cannot be selected, and show up as disabled on the select wheels.
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.
labelStyle String undefined Defines the position of the label. The default label style depends on the theme option. With the 'ios' theme the inputs have inline labels, with 'mobiscroll', 'material' and 'windows' themes the default label position is stacked. Possible values:
  • 'stacked'
  • 'inline'
  • 'floating'
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.
renderItem Function undefined

You can use the renderItem option to fully customize wheel items. It takes a function that has the item as parameter and it should return a ReactElement for that item.

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

The item parameter can have 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

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.

responsive Object undefined Specify different settings 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 settings for the given breakpoint.
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'
    }
}
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'.
showGroupWheel Boolean false

If true and the select has groups, two wheels are shown. The first contains the group labels, and the second one the options.

Groups can be specified by using the group property of the data items.

Check out the grouping data section to learn how to group data or the data binding section for more details on how to pass data to the Select component.

showInput Boolean true If true, it will render an input field for the component.
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) {
    }}
/>
onFilter(event, inst) Gets fired when the filter input gets updated. Filtering can be turned on with the filter option.

To fully customize the filtering, the default filter behavior can be prevented by returning false from the handler function. To learn more about the filtering check out the Filtering Section above.

Parameters

  • event: Object - The event object has the following properties:
    • filterText: the filter input's value
  • inst: Object - The instance object of the select.

Example

<mobiscroll.Select
    onFilter={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();
getTempVal()

Returns the temporary value that's selected on the picker.

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.

The value that has been set to the model can be aquired using the getVal() method.

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.
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();
setTempVal(value)

Sets the temporary value that's selected on the picker.

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 temporary value, check out the getTempVal instance method.

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.
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.
filterEmptyText String 'No results'

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

filterPlaceholderText String 'Search'

Text for the select filter input placeholder. The filtering can be turned on with the filter option.

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, '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'
  • Vietnamese: localeVi, 'vi'
import { Eventcalendar, localeDe } from '@mobiscroll/react';

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

In some cases it's more convenient to set the locale using the language code string. You can do that by using the locale object, which contains all translations by language codes as keys.

The locale object is not tree-shakeable, meaning that all translations present in the object will end up in the application bundle, whether it's being used or not.
import { Eventcalendar, locale } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={locale['de']} />;
}
rtl Boolean false Right to left display.
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.

Tree Shaking for styles

Tree shaking is a term commonly used in web development and particularly in JavaScript for unused code removal. Since websites are served (mostly) over the network, loading times depend on content size, so minification and unused content elimination plays a major role in making webapps fluid.

For the JavaScript part, popular frameworks already have the treeshaking built in, so the components that are not used will be left out from the built project.

Eliminating unused styles

In case of the styles, leaving out the unused rules is not as straight forward.
The overarching idea is that CSS selectors match elements in the DOM, and those elements in the DOM come from all sorts of places: your static templates, dynamic templates based on server-side state, and of course, JavaScript, which can manipulate the DOM in any way at all, including pull things from APIs and third parties.

Sass variables to the rescue

The Mobiscroll Library comes with a modular SASS bundle, that can be configured which component styles and which themes to leave in and out for the compiled css file.

Every component and theme has a SASS variable that can be turned on or off. If the variable is falsy the styles that it needs will not be added to the bundle.

Example on configuring the styles
// include the ios theme
$mbsc-ios-theme: true;

// include the components:
$mbsc-datepicker: true;
$mbsc-eventcalendar: true;
        
@import "@mobiscroll/react/dist/css/mobiscroll.modular.scss"

In the above example the styles needed for the eventcalendar and datepicker will be included and only for the ios theme. All other components (like select or grid-layout) and all other themes will be left out from the bundle.

It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.

Here's the complete list of the components and themes that can be used:

Some components use others internally, so it might happen that even though you don't want to include some styles, they will still end up in your bundle.
For example if you don't want to include the form components (input, button, segmented, etc...), but you are using the select component, the styles for the mobiscroll buttons, will still be in, because of the dependency.