General Calendar Cards Color Date & Time Event Calendar Forms Grid Layout Image Listview Measurement Navigation Number Numpad Option List Page Popup Range Scroller Scrollview Select Timer Timespan Treelist Tools Accessibility

Option List

The optionlist component is a UI tool that helps you easily implement common optionlist patterns.

Basic usage

The <mobiscroll.Optionlist /> renders an unordered list. Its children have to be list items.
Additionally to the Option List data attributes and options, it supports the following props:

Prop Type Description
className string Used to add css classes to the rendered list
Here is an example for the optionlist component
<mobiscroll.Optionlist display='inline'>
    <mobiscroll.OptionItem onClick={function() { alert('Menu 1 Clicked!'); }}>Menu 1</mobiscroll.OptionItem>
    <mobiscroll.OptionItem onClick={function() { alert('Menu 2 Clicked!'); }}>Menu 2</mobiscroll.OptionItem>
</mobiscroll.Optionlist>
Generating items dynamically
/* in your component */
constructor(props) {
    super(props);
    this.state = { selected: 'home' };
}

select = (item) => {
    this.setState({ selected: item.id });
}

render = () => {
    var items = [{id: 'home', text: 'Home', disabled: false, icon: 'home' },
        {id: 'feed', text: 'Feed', disabled: true, icon: 'pencil' },
        {id: 'settings', text: 'Settings', disabled: false, icon: 'user4'}
     ];

    return <mobiscroll.Optionlist display="inline">
        {items.map((item) => {
            return <mobiscroll.OptionItem key={item.id} id={item.id}
                selected={item.id == this.state.selected}
                disabled={item.disabled}
                icon={item.icon}
                onClick={this.select.bind(null, item)}
            >{item.text}</mobiscroll.OptionItem>
        })}
    </mobiscroll.Optionlist>

<mobiscroll.OptionItem /> props

Prop Type Description
selected bool Sets the item selected state
disabled bool Sets the item disabled state
icon string Sets the item icon
id string Sets the item id

Options

Name Type Default value Description
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
display String 'inline' Controls the position of the optionlist. Possible values:
  • 'inline' - Stay in the normal document flow.
  • 'top' - Fixed to top.
  • 'bottom' - Fixed to bottom.
itemWidth Number undefined If layout is 'fixed', it represents the exact witdh of the items in pixels, otherwise the minimum width of the items, and the items will be stretched to fill the container width.
layout String
Number
'liquid' Possible values:
  • 'liquid' - The number of displayed items will be calculated from the itemWidth option, if specified, items will be stretched to fill the container width.
  • 'fixed' - Item width will be defined by the content inside, or the itemWidth option, if specified.
  • integer - Number of items to display. If itemWidth is also specified, it will represent the maximum number of items to display.
mousewheel Boolean false Enables mousewheel / touchpad scroll.
paging Boolean false Scroll one page at a time. The page size will be the width of the container.
select String 'multiple' Defines the selection of the items. Possible values:
  • 'single' - Only one item can be selected at once.
  • 'multiple' - Multiple items can be selected.
  • 'off' - Selection is off.
snap Boolean false When the optionlist is scrolled it snaps to the edge of the last visible item which is at the opposite direction of the scroll.
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 the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'bootstrap' - Bootstrap themes
  • 'ios' - iOS theme
  • 'ios-dark' - iOS dark theme (deprecated)
  • 'material' - Material theme
  • 'material-dark' - Material dark theme (deprecated)
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll dark theme (deprecated)
  • 'windows' - Windows theme
  • 'windows-dark' - Windows dark theme (deprecated)
It's possible to modify theme colors or create custom themes.
Starting from v4.9.0 setting directly the dark version of the theme is deprecated. Use the themeVariant setting instead to control the light / dark appearance of the theme.
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' - Detect the preferred system theme on devices where this is supported.

If not set, only the theme setting will determine which theme to use.

To use the setting 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'.
The setting will not have any effect if the theme setting explicitly sets the dark version of a theme, e.g. theme: 'ios-dark'.
threshold Number 10 Minimum horizontal movement in pixels before the scrolling starts.

Events

Name Description
onAnimationEnd(event, inst) Gets fired when an autonomous scrolling/sliding ends.

Parameters

  • event: Object - The event object has the following properties:
    • destinationX: horizontal destination position.
    • destinationY: vertical destination position.
    • direction: direction of the movement expressed in degree: 90 - up, 180 - left, 270 - down, 360 - right.
    • duration: animation duration in milliseconds.
    • originX: horizontal starting position.
    • originY: vertical starting position.
    • posX: the horizontal movement from the initial position.
    • posY: the vertical movement from the initial position.
    • transitionTiming : transition-timing function.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onAnimationEnd={function (event, inst) {
    }}
/>
onAnimationStart(event, inst) Gets fired when an autonomous scrolling/sliding is starts.

Parameters

  • event: Object - The event object has the following properties:
    • destinationX: horizontal destination position.
    • destinationY: vertical destination position.
    • direction: direction of the movement expressed in degree: 90 - up, 180 - left, 270 - down, 360 - right.
    • duration: animation duration in milliseconds.
    • originX: horizontal starting position.
    • originY: vertical starting position.
    • posX: the horizontal movement from the initial position.
    • posY: the vertical movement from the initial position.
    • transitionTiming : transition-timing function.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onAnimationStart={function (event, inst) {
    }}
/>
onGestureEnd(event, inst) Gets fired when the user ends the scrolling gesture.

Parameters

  • event: Object - The event object has the following properties:
    • direction: direction of the movement expressed in degree: 90 - up, 180 - left, 270 - down, 360 - right.
    • originX: horizontal starting position.
    • originY: vertical starting position.
    • posX: the horizontal movement from the initial position.
    • posY: the vertical movement from the initial position.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onGestureEnd={function (event, inst) {
    }}
/>
onGestureStart(event, inst) Gets fired when the user ends the scrolling(swiping) gesture.

Parameters

  • event: Object - The event object has the following properties:
    • direction: direction of the movement expressed in degree: 90 - up, 180 - left, 270 - down, 360 - right.
    • originX: horizontal starting position.
    • originY: vertical starting position.
    • posX: the horizontal movement from the initial position.
    • posY: the vertical movement from the initial position.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onGestureStart={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 optionlist.

Example

<mobiscroll.Optionlist
    onInit={function (event, inst) {
    }}
/>
onItemTap(event, inst) Triggered when an item is tapped.

Parameters

  • event: Object - The event object has the following properties:
    • target: HTMLElement - The DOM element of the tapped item.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onItemTap={function (event, inst) {
    }}
/>
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onMarkupReady={function (event, inst) {
    }}
/>
onMove(event, inst) Gets fired when an autonomous scrolling/sliding ends.

Parameters

  • event: Object - The event object has the following properties:
    • destinationX: horizontal destination position.
    • destinationY: vertical destination position.
    • direction: direction of the movement expressed in degree: 90 - up, 180 - left, 270 - down, 360 - right.
    • duration: animation duration in milliseconds.
    • originX: horizontal starting position.
    • originY: vertical starting position.
    • posX: the horizontal movement from the initial position.
    • posY: the vertical movement from the initial position.
    • transitionTiming : transition-timing function.
  • inst: Object - The instance object of the optionlist.

Example

<mobiscroll.Optionlist
    onMove={function (event, inst) {
    }}
/>

Methods

Name Description
deselect(item) Deselects the specified item.

Parameters

  • item: HTMLElement or String - The DOM element of the item, or the id of the item (id must be present in the item's data-id attribute).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.deselect(1);
disable(item) Disables the specified item.

Parameters

  • item: HTMLElement or String - The DOM element of the item, or the id of the item (id must be present in the item's data-id attribute).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.disable(1);
enable(item) Enables the specified item

Parameters

  • item: HTMLElement or String - The DOM element of the item, or the id of the item (id must be present in the item's data-id attribute).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.enable(1);
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getInst();
navigate(item [, toggle ]) Scrolls the optionlist to the specified item.

Parameters

  • item: Object or String - The jQuery object or the id of the list item (id must be present in the item's data-id attribute).
  • toggle: Boolean - If true, it also toggles the selected state of the item and triggers the onItemTap event. If undefined, defaults to true in single select mode and to false in multiselect mode.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.navigate(1);
next([toggle]) Scrolls the optionlist to the next item.

Parameters

  • toggle (Optional): Boolean - If true, it also toggles the selected state of the item and triggers the onItemTap event. If undefined, defaults to true in single select mode and to false in multiselect mode.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.next();
option(options) Sets one or more options for the component.

Parameters

  • options: Object - A map of option-value pairs to set.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});
prev([toggle]) Scrolls the optionlist to the previous item.

Parameters

  • toggle (Optional): Boolean - If true, it also toggles the selected state of the item and triggers the onItemTap event. If undefined, defaults to true in single select mode and to false in multiselect mode.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.prev();
refresh() Recalculate dimensions needed for scrolling.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.refresh();
select(item) Selects the specified item.

Parameters

  • item: HTMLElement or String - The DOM element of the item, or the id of the item (id must be present in the item's data-id attribute).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.select(2);
tap(el, handler) Attaches the handler function to the tap event of element el.

Parameters

  • el: Object - The element with tap event.
  • handler: Function - If the action was initiated with touch event, handler is called on touchend, otherwise on click.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Name Type Default value Description
lang String 'en-US' Language of the component. Based on the language string the component loads the language based default settings from the language modules.
Supported languages:
  • Arabic: 'ar'
  • Bulgarian: 'bg'
  • Catalan: 'ca'
  • Czech: 'cs'
  • Chinese: 'zh'
  • Croatian: 'hr'
  • Danish: 'da'
  • Dutch: 'nl'
  • English: 'en' or 'en-US' or undefined
  • English (UK): 'en-UK' or 'en-GB'
  • Farsi: 'fa'
  • German: 'de'
  • Greek: 'el'
  • Spanish: 'es'
  • Finnish: 'fi'
  • French: 'fr'
  • Hebrew: 'he'
  • Hindi: 'hi'
  • Croatian: 'hr'
  • Hungarian: 'hu'
  • Italian: 'it'
  • Japanese: 'ja'
  • Korean: 'ko'
  • Lithuanian: 'lt'
  • Norwegian: 'no'
  • Polish: 'pl'
  • Portuguese (Brazilian): 'pt-BR'
  • Portuguese (European): 'pt-PT'
  • Romanian: 'ro'
  • Russian: 'ru'
  • Russian (UA): 'ru-UA'
  • Slovak: 'sk'
  • Serbian: 'sr'
  • Thai: 'th'
  • Swedish: 'sv'
  • Turkish: 'tr'
  • Ukrainian: 'ua'
  • Vietnamese: 'vi'
rtl Boolean false Right to left display.

Data attributes

Name Description
data-disabled If true the optionlist item will be disabled.
data-icon With this attribute item icons can be defined. It needs a font-icon name.

You can build your custom icon set on our download page ("Choose Icon Set" section).

See the full list of available icons here.

The default icon pack contains the following icons:
  • home
  • pencil
  • office
  • newspaper
  • droplet
  • image2
  • camera
  • play
  • bullhorn
  • connection
  • library
  • book
  • file4
  • copy2
  • copy3
  • stack
  • folder
  • tag
  • cart
  • support
  • phone
  • location
  • credit
  • map
  • history
  • clock
  • alarm2
  • stopwatch
  • calendar
  • mobile
  • drawer
  • undo2
  • redo2
  • forward
  • reply
  • bubble
  • bubbles
  • disk
  • download
  • upload
  • user4
  • key2
  • lock2
  • unlocked
  • cogs
  • aid
  • bars
  • cloud-download
  • cloud-upload
  • globe
  • airplane
  • earth
  • link
  • flag
  • eye
  • eye-blocked
  • attachment
  • star3
  • heart
  • thumbs-up
  • thumbs-up2
  • smiley2
  • sad2
  • checkmark
  • close
  • plus
  • minus
  • remove
  • loop2
You can use the icons anywhere in your app using the mbsc-ic mbsc-ic-{iconName} classes, e.g.:
<div class="mbsc-ic mbsc-ic-star"></div>
data-selected If true the optionlist item will be selected.

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 Optionlist component or affect its look:

Global variables

These variables are applied to all base themes: iOS, material, windows and mobiscroll.
They all come in pairs. One for the light and one for the dark variant in each theme.

Variable name Description
$mbsc-nav-background-light Sets the background color of the Optionlist
$mbsc-nav-background-dark
$mbsc-nav-text-light Sets the text color of the Optionlist
$mbsc-nav-text-dark
$mbsc-nav-accent-light Sets the accent color of the Optionlist
$mbsc-nav-accent-dark

If you really want to get sophisticated or if a color doesn't look good on a specific theme and you want to overwrite it, you can fine tune all of the above variables individually for each theme.
Below are the complete list of variables broken down to themes:

iOS theme

Variable name Default value Description
$mbsc-ios-nav-background
#f7f7f7
The Optionlist background color
$mbsc-ios-nav-text
#878787
The Optionlist text color
$mbsc-ios-nav-accent
#007bff
The Optionlist accent color

iOS Dark theme

Variable name Default value Description
$mbsc-ios-dark-nav-background
#000000
The Optionlist background color
$mbsc-ios-dark-nav-text
#ababab
The Optionlist text color
$mbsc-ios-dark-nav-accent
#ff8400
The Optionlist accent color

Windows theme

Variable name Default value Description
$mbsc-windows-nav-background
#f2f2f2
The Optionlist background color
$mbsc-windows-nav-text
#262626
The Optionlist text color
$mbsc-windows-nav-accent
#0078d7
The Optionlist accent color

Windows Dark theme

Variable name Default value Description
$mbsc-windows-dark-nav-background
#191919
The Optionlist background color
$mbsc-windows-dark-nav-text
#ffffff
The Optionlist text color
$mbsc-windows-dark-nav-accent
#0078d7
The Optionlist accent color

Material theme

Variable name Default value Description
$mbsc-material-nav-background
#eeeeee
The Optionlist background color
$mbsc-material-nav-text
#5b5b5b
The Optionlist text color
$mbsc-material-nav-accent
#009688
The Optionlist accent color

Material Dark theme

Variable name Default value Description
$mbsc-material-dark-nav-background
#303030
The Optionlist background color
$mbsc-material-dark-nav-text
#c2c2c2
The Optionlist text color
$mbsc-material-dark-nav-accent
#81ccc4
The Optionlist accent color

Mobiscroll theme

Variable name Default value Description
$mbsc-mobiscroll-nav-background
#f7f7f7
The Optionlist background color
$mbsc-mobiscroll-nav-text
#454545
The Optionlist text color
$mbsc-mobiscroll-nav-accent
#4eccc4
The Optionlist accent color

Mobiscroll Dark theme

Variable name Default value Description
$mbsc-mobiscroll-dark-nav-background
#253238
The Optionlist background color
$mbsc-mobiscroll-dark-nav-text
#f7f7f7
The Optionlist text color
$mbsc-mobiscroll-dark-nav-accent
#4fccc4
The Optionlist accent color