General
Getting Started
Quick Install
Using with Cordova
Using with Ionic
Using with Meteor
Mobiscroll CLI
ES6 Modules
Instance
Customizing the Look and Feel
Upgrade From Trial
Utility functions
Update version
Upgrade Guide v4
Date & Time pickers
Event Calendar
Form components
Accordion
Alerts & Notifications
Buttons
Checkbox
Dropdown
Forms
Progress
Radio Buttons
Rating
Segmented
Slider
Stepper
Switch
Textfields
Timer
Responsive list
Numeric pickers
Pickers & dropdowns
Layout & navigation
Tools
Accessibility
Listview
Basic usage
The Mobiscroll Listview control can be used as the <mobiscroll.Listview /> react component.
Additionally to the Listview options the following props can be used:
The listview items can be customized, so in order to render them a React Component is needed. It can be a simple li element or any custom made component, that renders an li element.
A few simple listview item examples
// a function as listview item
function MyListItem(props) {
return <li>{this.props.item.text}</li>
}
// a class as listview item
class MyListItem extends React.Component {
render() {
return <li>{this.props.item.text}</li>;
}
}This MyListItem component will get the data item as it's item prop.
class MyWrapper extends React.Component {
constructor(props) {
super(props);
this.state = {
items: [{
id: 1,
text: 'First Item'
}, {
id: 2,
text: 'Second Item'
}]
};
}
render() {
return <div>
<mobiscroll.Listview theme="ios" itemType={MyListItem} data={this.state.items} />
</div>;
}
}Animations
The Listview will automatically animate the items added to the list.
To animate listitem removals the
React.adddons.TransitionGroup component is required.As of React v15.5 the React.addons entry point is deprecated and the add-ons moved to different modules. Here's an example how to load the TransitionGroup from it's module:
First step is to install the module:
$ npm install react-transition-group@1.x --saveSecond step is to import it in your app. Then pass it to the react namespace under addons:
import React from 'react';
// import the TransitionGroup from it's module
import TransitionGroup from 'react-transition-group/TransitionGroup';
// pass it to the React.addons namespace
React.addons = {
TransitionGroup: TransitionGroup
};Working with the data
To manipulate the data array, it is highly recommended to use the immutability helpers. The example below demonstrates it's use.
Learn more
Here is a full example of the listview:
import { Listview, Form, Button } from '@mobiscroll/react';
import update from 'immutability-helper';
class App extends React.Component {
constructor(props) {
super(props);
this.state = {
items: [{
id: 1,
text: 'First Item'
}, {
id: 2,
text: 'Second Item'
}]
};
this.addToEnd = this.addToEnd.bind(this);
this.removeLast = this.removeLast.bind(this);
}
// used when swiping an item
stages = {
left: [{
key: "stage1",
icon: "remove",
color: "crimson",
text: "Remove",
action: (event, inst) => {
this.setState(update(this.state, { items: { $splice: [[event.index, 1]] } }));
}
}]
};
addToEnd() {
// Generating a random item
var id = Math.floor(Math.random() * 1000);
var newItem = { id: id, text: 'Generated ' + id };
// calculating the new state
var newState = update(this.state, { items: { $push: [newItem] } });
this.setState(newState);
}
removeLast() {
var newState = update(this.state, { items: { $splice: [[-1, 1]] } });
this.setState(newState);
}
render() {
return (<>
<Listview itemType={MyListviewItem} data={this.state.items} stages={this.stages} />
<Form>
<Button onClick={this.addToEnd}>Add to the End</Button>
<Button onClick={this.removeLast}>Remove the Last</Button>
</Form>
);
}
}For many more examples - simple and complex use-cases - check out the listview demos for react.
Options
| Name | Type | Default value | Description |
|---|---|---|---|
| actionable | boolean | true |
If set to false, hover effects on the listview items will be turned off. This option can be defined inside the itemGroups setting as well for specific items. |
| actions | Array, Object | undefined |
An array or an object which defines an icon list whit different actions. If an array, the same icon list will be displayed on both left and right swipe.
An action object has the following properties:
A sample action array: If an object, a different icon list can be defined to both sides, swipe will be allowed just for the defined side. A sample action object: |
| actionsWidth | Number | 90 |
Specifies the width in percentage of the actions container. |
| animateAddRemove | Boolean | true |
If set to false, item add and remove will not be animated. |
| animateIcons | Boolean | true |
If false the icon won't be animated when a list item is swiped. |
| context | String, HTMLElement | 'body' |
The scrollable DOM element containing the listview. Can be a selector string or a DOM element. |
| display | String | 'inline' |
Controls the position of the listview. Possible values:
|
| fillAnimation | Boolean | true |
If true the sortable item will be highlighted with a fill animation. |
| fixedHeader | Boolean | false |
If true, the group headers will be positioned as fixed (will stay on top, if it's scrolled out of view, until the next group header is reached). |
| hover | String, Object | undefined |
On a list item mouse pointer hover shows the underlying action menu. The direction of the reveal can be specified by passing 'left' or 'right' parameter, or with the hover objects direction property. The hover object can have a time and a timeout property to define the reveal animation time and the hover start timeout in milliseconds. Sample hover object: |
| iconSlide | Boolean | false |
If true, the icon and text of an action is slided along the edge of the slided item. |
| itemGroups | Object | undefined |
It can be used to define different actions and settings for a group of items. The items can be grouped using the data-type attribute of the list element.
If an item has no data-type attribute, the settings defined outside itemGroups will be used.HTML
Javascript
|
| loadingIcon | String | 'loop2' |
Specifies the icon inside the loading content. |
| navigateOnDrop | Boolean | false |
If the list is sortable and multiLevel flag is set, if an element is dropped on a parent element, or back button, the element will be appended to the sublist / parent list. The navigateOnDrop is true, after the element is dropped, the list will be navigated to the sub list or parent list. |
| quickSwipe | Boolean | true |
If true, a quick swipe (duration is less than 300ms and movement is more than 50px) executes the action of the first stage in the swipe direction, even if the stage's percent is not reached. |
| select | String | 'off' |
Defines the selection of the items. Possible values:
|
| sortable | Boolean Object |
undefined |
If true, or an object the list will be sortable. By passing an object, you can set additional sort options:
|
| sortDelay | Number | 200 |
Delay after tap in milliseconds until sort mode is activated on the item. |
| stages | Array , Object | [] |
An array of objects which defines the different stages when swiping a list item.
Or it can be an object with 'left' and 'right' property with which different stages can be defined for both sides.
A stage object has the following properties:
See the full list of available icons here. The default icon pack contains the following icons: You can use the icons anywhere in your app using thembsc-ic mbsc-ic-{iconName} classes, e.g.:
|
| striped | Boolean | false |
If true, the list items will have alternate (striped) styling. |
| swipe | Boolean, String, or Function | true |
If false, swipe is not allowed. If 'left' or 'right', swipe is allowed only in the given direction.If a function, the returned value will be used, which can be any of the above. Receives an argument object and the Listview instance as parameters. The arguments object has the following properties:
|
| swipeleft | Function | undefined |
Action to execute when a list item is swiped left.
Receives an argument object and the Listview instance as parameters.
The arguments object has the following properties:
|
| swiperight | Function | undefined |
Action to execute when a list item is swiped right.
Receives an argument object and the Listview instance as parameters.
The arguments object has the following properties:
|
| theme | String | undefined |
Sets the visual appearance of the component.
If it is If the theme for the specific platform is not present, it will default to the Mobiscroll theme. Supplied themes:
Starting from v4.9.0 setting directly the dark version of the theme is deprecated.
Use the themeVariant option 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:
If not set, only the theme setting will determine which theme to use.
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
The option will not have any effect if the theme option explicitly
sets the dark version of a theme, e.g.
theme: 'ios-dark'.
|
| vibrate | Boolean | true |
Turn vibration on/off on sort start and sort end. |
Events
| Name | Description | |
|---|---|---|
| onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example |
|
| onItemAdd(event, inst) | This event is triggered when an item is added.
Parameters
Example |
|
| onItemRemove(event, inst) | This event is triggered when an item is removed.
Parameters
Example |
|
| onItemTap(event, inst) |
Triggered when an item is tapped.
In case of parent items or back items hierarchical navigation can be prevented by returning false from this event.
Parameters
Example |
|
| onListEnd(event, inst) |
Triggered when scrolling reaches to the end of the listview.
Parameters
Example |
|
| onNavEnd(event, inst) | This event is triggered when hierarchical navigation ends.
Parameters
Example |
|
| onNavStart(event, inst) | This event is triggered when hierarchical navigation starts.
Parameters
Example |
|
| onSlideEnd(event, inst) | This event is triggered when a slide ended.
Parameters
Example |
|
| onSlideStart(event, inst) | This event is triggered when a slide started.
Parameters
Example |
|
| onSort(event, inst) |
Triggered during sorting, is being fired continuosly when the item is dragged.
Parameters
Example |
|
| onSortChange(event, inst) |
Triggered during sorting, but only when the DOM position has changed.
It also has the visual feedback that the items in the background are moving to make place for the dragged item.
Parameters
Example |
|
| onSortEnd(event, inst) |
Triggered when sorting has stopped.
Parameters
Example |
|
| onSortStart(event, inst) |
Triggered when sorting starts.
Parameters
Example |
|
| onSortUpdate(event, inst) |
Triggered when the user stopped sorting and the DOM position has changed.
Parameters
Example |
|
| onStageChange(event, inst) | This event is triggered during sliding when the stage changes.
Parameters
Example |
|
Methods
| Name | Parameters | Description |
|---|---|---|
| add(id, markup [, index ] [, callback ] [, parent ]) | Adds a new list item to the list with the given id and markup at the specified index.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| addUndoAction(func) |
Push an undo action into the undo stack. Accepts a function as parameter. If it's called multiple times between
startActionTrack and endActionTrack calls, all actions will be added to one action group, and will be undone by one single undo call (like a transaction).
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| close(item [, time ]) |
Closes the given item, if it's actions or stages are opened.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| deselect(item) | Deselects the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| endActionTrack() | All actions between startActionTrack and endActionTrack calls will be handled as one action group, and will be undone by one single undo call (like a transaction).
ExampleMethods can be called on an instance. For more details see calling methods |
|
| hideLoading() |
Hides the loading content. By default the loading content is hidden.
ExampleMethods can be called on an instance. For more details see calling methods |
|
| move(item, index [, direction ][, callback ]) | Moves a list item to another position in the list.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| navigate(item) |
Brings the specified item into view. If the listview is hierarchical and the item is not in the currently visible level, the listview will slide to the item's level.
If the listview is not currently in the viewport, the viewport will be scrolled to the item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| openActions(item, direction [, time ] [, demo ]) | Opens the actions of a list item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| openStage(item, stage [, time ] [, demo ]) | Opens the specified stage of a list item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| option(options) |
Sets one or more options for the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| remove(item [, direction ] [, callback ]) | Removes a list item from the list.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| select(item) |
Selects the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| showLoading() |
Shows the loading content. By default the loading content is hidden.
ExampleMethods can be called on an instance. For more details see calling methods |
|
| startActionTrack() | All actions between startActionTrack and endActionTrack calls will be handled as one action group, and will be undone by one single undo call (like a transaction).
ExampleMethods can be called on an instance. For more details see calling methods |
|
| tap(el, handler) |
Attaches the handler function to the tap event of element el.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| undo() | Last action will be undone.
ExampleMethods can be called on an instance. For more details see calling methods |
|
Data attributes
| Name | Description |
|---|---|
| data-icon |
Display an icon inside the list item. It needs a font-icon name.
Only works if the enhance option is true.
|
| data-icon-align |
Specify icon alignment. It can be "left" or "right", it defaults to "left" if not specified.
Only works if the enhance option is true.
|
| data-selected | Sets the initially selected listview items. |
| data-role | If the list item contains a data-role="list-divider" attribute, than that item will be displayed as a list divider. |
| data-type | The items can be grouped using the data-type attribute of the list element. More about groups: itemGroups. |
Localization
| Name | Type | Default value | Description |
|---|---|---|---|
| backText | String | 'Back' |
Text for the back button, in case of hierarchical lists. |
| 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:
|
| rtl | Boolean | false |
Right to left display. |
| undoText | String | 'Undo' |
Text for the undo action. |
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"
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:
- Theme specific variables (ex.
$mbsc-material-background,$mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here. - Component specific global variables (ex.
$mbsc-card-background-light,$mbsc-listview-text-dark) are applied to all themes for a specific component. - 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.
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-listview-background-light | Sets the background color of the listview |
| $mbsc-listview-background-dark | |
| $mbsc-listview-text-light | Sets the text color of the listview |
| $mbsc-listview-text-dark | |
| $mbsc-listview-accent-light | Sets the accent color of the listview |
| $mbsc-listview-accent-dark | |
| $mbsc-listview-header-background-light | Sets the group header background color |
| $mbsc-listview-header-background-dark | |
| $mbsc-listview-header-text-light | Sets the group header text color |
| $mbsc-listview-header-text-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-listview-background | #ffffff | The listview background color |
| $mbsc-ios-listview-text | #000000 | The listview text color |
| $mbsc-ios-listview-accent | #007bff | The listview accent color |
| $mbsc-ios-listview-header-background | #efeff4 | The group header background color |
| $mbsc-ios-listview-header-text | #707070 | The group header text color |
iOS Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-ios-dark-listview-background | #0f0f0f | The listview background color |
| $mbsc-ios-dark-listview-text | #ffffff | The listview text color |
| $mbsc-ios-dark-listview-accent | #ff8400 | The listview accent color |
| $mbsc-ios-dark-listview-header-background | #1a1a1a | The group header background color |
| $mbsc-ios-dark-listview-header-text | #8f8f8f | The group header text color |
Windows theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-windows-listview-background | #f2f2f2 | The listview background color |
| $mbsc-windows-listview-text | #262626 | The listview text color |
| $mbsc-windows-listview-accent | #0078d7 | The listview accent color |
| $mbsc-windows-listview-header-background | #ffffff | The group header background color |
| $mbsc-windows-listview-header-text | #262626 | The group header text color |
Windows Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-windows-dark-listview-background | #191919 | The listview background color |
| $mbsc-windows-dark-listview-text | #ffffff | The listview text color |
| $mbsc-windows-dark-listview-accent | #0078d7 | The listview accent color |
| $mbsc-windows-dark-listview-header-background | #000000 | The group header background color |
| $mbsc-windows-dark-listview-header-text | #ffffff | The group header text color |
Material theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-material-listview-background | #eeeeee | The listview background color |
| $mbsc-material-listview-text | #5b5b5b | The listview text color |
| $mbsc-material-listview-accent | #000000 | The listview accent color |
| $mbsc-material-listview-header-background | #eeeeee | The group header background color |
| $mbsc-material-listview-header-text | #009688 | The group header text color |
Material Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-material-dark-listview-background | #303030 | The listview background color |
| $mbsc-material-dark-listview-text | #c2c2c2 | The listview text color |
| $mbsc-material-dark-listview-accent | #ffffff | The listview accent color |
| $mbsc-material-dark-listview-header-background | #303030 | The group header background color |
| $mbsc-material-dark-listview-header-text | #81ccc4 | The group header text color |
Mobiscroll theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-mobiscroll-listview-background | #f7f7f7 | The listview background color |
| $mbsc-mobiscroll-listview-text | #454545 | The listview text color |
| $mbsc-mobiscroll-listview-accent | #4eccc4 | The listview accent color |
| $mbsc-mobiscroll-listview-header-background | #f7f7f7 | The group header background color |
| $mbsc-mobiscroll-listview-header-text | #4eccc4 | The group header text color |
Mobiscroll Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-mobiscroll-dark-listview-background | #263238 | The listview background color |
| $mbsc-mobiscroll-dark-listview-text | #f7f7f7 | The listview text color |
| $mbsc-mobiscroll-dark-listview-accent | #4fccc4 | The listview accent color |
| $mbsc-mobiscroll-dark-listview-header-background | #263238 | The group header background color |
| $mbsc-mobiscroll-dark-listview-header-text | #4fccc4 | The group header text color |
