Contents
v4
General Date & Time pickers Event Calendar Form components Responsive list Numeric pickers Pickers & dropdowns Layout & navigation Tools Accessibility
Version 4.10.10 for Angular
5.22.3
final
4.10.10
final
3.2.6
final
2.17.3
final
Javascript jQuery Angular AngularJS React
General Date & Time pickers Event Calendar Form components Responsive list Numeric pickers Pickers & dropdowns Layout & navigation
Grid Layout Navigation Page
Usage Options Events Methods Localization Typography Empty view Note Images Theming
Popup
Tools Accessibility

Listview

Basic usage

The listview component can be used to enhance list with gesture, swipe and drag & drop support.

Here's a basic example of displaying a static list:

Basic example
<!-- Simple listview -->
<mbsc-listview>
    <mbsc-listview-item>Item 1</mbsc-listview-item>
    <mbsc-listview-item>Item 2</mbsc-listview-item>
    <mbsc-listview-item>Item 3</mbsc-listview-item>
</mbsc-listview>

<!-- Listview with groups -->
<mbsc-listview>
    <mbsc-listview-header>First Group</mbsc-listview-header>
    <mbsc-listview-item>Item 1</mbsc-listview-item>
    <mbsc-listview-item>Item 2</mbsc-listview-item>
    <mbsc-listview-header>Second Group</mbsc-listview-header>
    <mbsc-listview-item>Item 3</mbsc-listview-item>
    <mbsc-listview-header>Third Group</mbsc-listview-header>
</mbsc-listview>

Rendering items dynamically

Using the angular built in ngFor directive to render the listview items dynamically:

Dynamic items
<mbsc-listview>
    <mbsc-listview-item *ngFor="let item in listItems">{{item}}</mbsc-listview-item>
</mbsc-listview>
export class MyExampleComponent {
    listItems: string[] = ['Item 1', 'Item 2', 'Item 3'];
}

Adding & Removing items

When the listview items are generated dynamically from an array, adding and removing items are done by pushing and removing items to and from the associated data array.

Add/remove list items
<mbsc-listview>
    <mbsc-listview-item *ngFor="let item in listItems">{{item}}</mbsc-listview-item>
</mbsc-listview>

<mbsc-button (click)="addNextItem()">Add Item</mbsc-button>
<mbsc-button (click)="removeLastItem()">Remove Last</mbsc-button>
export class MyExampleComponent {
    listItems: string[] = ['Item 1', 'Item 2', 'Item 3'];

    addNextItem(): void {
        this.listItems.push('Item ' + (this.listItems.length + 1));
    }

    removeLastItem(): void {
        this.listItems.pop();
    }
}

It is a common practice to fetch items from a service and populate the listview.

Here is an example of getting the listview items from an API that serves JSON data. The example uses the angular built in Http service.

Fetching items from a service
<mbsc-listview>
    <mbsc-listview-item *ngFor="let item of data">{{item}}</mbsc-listview-item>
</mbsc-listview>
import { Http } from '@angular/http';
import { OnInit } from '@angular/core';

export class MyExampleComponent {
    data: any[] = [];

    constructor(private http: Http) {}

    ngOnInit() {
        this.http.get('//some-server.com/some-api.json').subscribe(res => {
            this.data = JSON.parse(res._body); // response should be an array of items ex.: ['item 1', 'item 2']
        });
    }
}

Customizing the listview

The listview can be customized with various settings. These settings can be passed to the listview as individual settings inline or grouped into one object.

Example of passing settings
<!-- Passing individual settings inline -->
<mbsc-listview theme="ios" [swipe]="false" [striped]="true" >
    <mbsc-listview-item>Item 1</mbsc-listview-item>
    <mbsc-listview-item>Item 2</mbsc-listview-item>
    <mbsc-listview-item>Item 3</mbsc-listview-item>
</mbsc-listview>

<!-- Passin all settings grouped into an object -->
<mbsc-listview [options]="myGroupedOptions" >
    <mbsc-listview-item>Item 1</mbsc-listview-item>
    <mbsc-listview-item>Item 2</mbsc-listview-item>
    <mbsc-listview-item>Item 3</mbsc-listview-item>
</mbsc-listview>
export class MyExampleComponent {
    myGroupedOptions: MbscListviewOptions = {
        theme: 'ios',
        swipe: false,
        striped: true
    };
}

Handling selection and swipe

There are multiple ways of selecting an item on the listview depending on the use case. Here are the most common ones:

Example of selection and swipe
<!-- removing items on swipe -->
<mbsc-listview [options]="myGroupedOptions">
    <mbsc-listview-item *ngFor="let item of data" [id]="item.id" (click)="selected(item)">{{item.text}}</mbsc-listview-item>
</mbsc-listview>
export class MyExampleComponent {
    data: any[] = [{ id: 1, text: 'Item 1' }, { id: 2, text: 'Item 2' }];
    
    myGroupedOptions: MbscListviewOptions = {
        swipe: 'left',
        swipeLeft: (e, inst) => {
            this.data.splice(e.index, 1); // removes the swiped item
        }
    };

    selected(i: any): void {
        console.log('Selected ' + i.text);
    }
}

Passing events

All events can be used inline with the component. When passing event handlers inline, the instance of the component becomes the inst property of the event object.

Passing inline event handlers
<!-- simple handler -->
<mbsc-listview (onItemTap)="simpleTap()">
    ...
</mbsc-listview>

<!-- handler with default event -->
<mbsc-listview (onItemTap)="withDefaultEvent($event)">
    ...
</mbsc-listview>

<!-- handler with additional parameter -->
<mbsc-listview (onItemTap)="withAdditionalEvent($event, 'myAddition')">
    ...
</mbsc-listview>

export class MyExampleComponent {
    // simple handler without any parameters
    simpleTap() {
        console.log('simple handler'); // prints 'simple handler'
    }

    // event handler with the default event parameter
    withDefaultEvent(event: any) {
        console.log(event, event.inst); // prints the event object and the mobiscroll listview control instance
    }

    // event handler with additional parameters
    withAdditionalEvent(event: any, addition: string) {
        console.log(addition); // prints 'myAddition'
    }
}

For more examples with the listview component checkout the demos section.

Using with Ionic

The Listiview components can be used tha same way with Ionic, as any other angular component.

Modules

The MbscListviewModule can be used to import all the components from below.

Components

Component Description
<mbsc-listview> Listview component
<mbsc-listview-item> Listview item component
<mbsc-listview-header> Listview header component

Attributes

Attribute Data type Description
[options] MbscListviewOptions Attribute used to pass the mobiscroll options

For many more examples - simple and complex use-cases - check out the listview demos for angular.

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:
  • icon - Icon of the action.
  • color (Optional) - Color of the action.
  • text (Optional) - Text of the action.
  • disabled - Indicates if the action of the stage is disabled or not. If true, the action will not be executed and the item is reverted to the original position. Function is also accepted, receives the Mobiscroll Listview object and the event object as parameters.
  • action - A function which is executed if the swipe is finished and the stage was active. Receives the Mobiscroll Listview object and the event object as parameters.
  • undo - Indicates if the action can be undone. If true or a function, an undo icon will appear after the action is executed. All the UI operations on the listview will be restored (e.g. remove, add, move, sort). If other, user defined operations needs to be undone, (e.g. server side operations), they should be specified in the undo function.


A sample action array: 
[   
    {    
        icon: 'thumbs-up',  
        action: (event, inst) => {}
    },
    {
        icon: 'thumbs-up2',  
        action: (event, inst) => {}
    }
]

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: 
{   
    left: [
        { 
            icon: 'smiley2',  
            action: (event, inst) => {}
        },
        { 
            icon: 'remove',  
            disabled: (event, inst) => {
                // Disable this action only for the item with 12 as id. 
                if (event.target.getAttribute('data-id') === '12') {
                    return true;
                }
            },
            action: (event, inst) => {}
        }
    ],
    right: [
        { 
            icon: 'heart',  
            action: (event, inst) => {}
        },
        { 
            icon: 'plus', 
            disabled: true,
            action: (event, inst) => {}
        }
    ]
}
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:
  • 'inline' - Stay in the normal document flow.
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: 
{    
    time: 300,        // reveal animation time, by default is 200ms
    timeout: 150,     // hover start timeout, by default is 200ms
    direction: "left" // direction of the reveal, by default is "right"
}
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
<ul id="mylist">
    <li data-type="type1">Item 1</li>
    <li data-type="type2">Item 2</li>
    <li data-type="type3">Item 3</li>
</ul>
Javascript
$('#mylist').mobiscroll().listview({
    itemGroups: {
        type1: {
            stages: [ /* Define stages here */ ],
            tap: function () { alert('Tap on type 1'); }
        },
        type2: {
            actions: [ /* Define actions here */ ]
            tap: function () { alert('Tap on type 2'); }
        }
        type3: {
            swipe: false
        }
    }
});
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:
  • 'single' - Only one item can be selected at once.
  • 'multiple' - Multiple items can be selected.
  • 'off' - Selection is off.
sortable Boolean
Object		 undefined If true, or an object the list will be sortable. By passing an object, you can set additional sort options:
  • handle - If true or 'right' a sort handle will appear in the right side if 'left' on the left side of the list items, which only allows sort if touch started on the handle (false if not specified).
  • group - If true, sort is allowed between groups (true if not specified).
  • multiLevel - If true, sort is allowed between levels of the hierarchy (true if not specified).
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:
  • percent (Optional) - The percentage of swipe when the stage activates. Use positive values for right swipe, negative values for left swipe. Percentage is autogenerated if is not specified.
  • color (Optional) - Background color behind the swiped list item when the stage is active.
  • icon (Optional) - Icon to show when the stage is active.
  • text (Optional) - Text to show when the stage is active. Function is also accepted, receives the jQuery object of the swiped list item, the item's index in the list as parameters, and the Mobiscroll Listview object.
  • confirm (Optional) - Indicates if the action of the stage should be confirmed or not. If yes, the item is not reverted after slide ends, and a tap on the stage (icon, text, or background) confirms the action, tapping everywhere else cancels the action. Function is also accepted, receives the jQuery object of the swiped list item, the item's index in the list as parameters, and the Mobiscroll Listview object.
  • disabled (Optional) - Indicates if the action of the stage is disabled or not. If true, the action will not be executed and the item is reverted to the original position. Function is also accepted, receives the Mobiscroll Listview object and the event object as parameters.
  • key (Optional) - specify a unique identifier. It uses the openStage function for opening stages programmatically.
  • action (Optional) - A function which is executed if the swipe is finished and the stage was active. Receives the Mobiscroll Listview object and the event object as parameters.
  • undo (Optional) - Indicates if the action can be undone. If true or a function, an undo icon will appear after the action is executed. All the UI operations on the listview will be restored (e.g. remove, add, move, sort). If other, user defined operations needs to be undone, (e.g. server side operations), they should be specified in the undo function.
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>
A sample stage array: 
[   
    {    
        percent: -20,
        color: "red",
        icon: "minus",
        disabled: true,
        action: (event, inst) => {}
    },
    { 
        percent: 20,
        color: "green",
        icon: "plus",
        disabled: (event, inst) => {
            // Disable this action only for the item with 12 as id. 
            if (event.target.getAttribute('data-id') === '12') {
                return true;
            }
        },
        action: (event, inst) => {}
    }
]
A sample stage object: 
{
    left: [
        {   
            key: "stage1", 
            icon: "phone", 
            color: "crimson", 
            text: "call", 
            action: (event, inst) => {}
        },
    ],
    right: [
        { 
            key: "stage3", 
            icon: "bubble", 
            color: "olive", 
            text: "Message", 
            action: (event, inst) => {}
        }
    ]
}
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:
  • target:HTMLElement - The list item the swipe was initiated on.
  • index:Number - Index of the item in the list.
  • direction:String - Direction of the swipe gesture, 'left' or 'right'.
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:
  • target:HTMLElement - The list item the swipe was initiated on.
  • index:Number - Index of the item in the list.
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:
  • target:HTMLElement - The list item the swipe was initiated on.
  • index:Number - Index of the item in the list.
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 default to the Mobiscroll theme.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'mobiscroll' - Mobiscroll theme
  • 'windows' - Windows theme
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 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:
  • '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.

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 '-dark', e.g.: 'my-theme' and 'my-theme-dark'.

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.

Setting options dynamically

There are two ways to modify options after initalization

  1. Using the option method.

    The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).

    Here is an example for the dynamic option change
    import { ViewChild } from '@angular/core';
@Component({
    selector: 'my-example',
    template: `
        <input mbsc-listview #myVariable="mobiscroll" [(ngModel)]="myExample"/>
        <button (click)="changeOptions()">Change theme and language</button>
    `
})
export class MyExample {
    @ViewChild('myVariable') 
    myRef: any;

    // Modify options
    changeOptions() {
        this.myRef.instance.option({
            theme: 'mobiscroll',
            lang: 'de'
        });
    }
}
  2. Modify directly the settings object.

    Useful when changing dynamic settings, which do not need redraw (e.g. vibrate, calendar marked days).

    Example
    import { ViewChild } from '@angular/core';
@Component({
    selector: 'my-example',
    template: `
        <input mbsc-listview #myVariable="mobiscroll" [mbsc-options]="myOptions"/>
        <button (click)="changeOptions()">Change Vibration</button>
    `
})
export class MyExample {
    @ViewChild('myVariable') 
    myRef: any;

    // get instance and modify a setting
    changeOptions() {
        this.myRef.instance.settings.vibrate = true;
    }
    
    // Modify settings in an event
    myOptions: any = {
        onItemTap: (event, inst) => {
            inst.settings.vibrate = true;
        }
    }
}

Events

Using arrow functions is recommended so you have access to your outer component instance inside event handlers through this reference.
When using the events inline (see here) the inst parameter is passed as a property to the event.
Name Description
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onInit: (event, inst) => {
        }
    }
}
onItemAdd(event, inst) This event is triggered when an item is added.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the added list item.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onItemAdd: (event, inst) => {
        }
    }
}
onItemRemove(event, inst) This event is triggered when an item is removed.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the added list item.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onItemRemove: (event, inst) => {
        }
    }
}
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

  • event: Object - The event object has the following properties:
    • target: HTMLElement - DOM element of the tapped list item.
    • domEvent: Event - The DOM event fired on tap.
    • index: Number - The index of the item in the list.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onItemTap: (event, inst) => {
        }
    }
}
onListEnd(event, inst) Triggered when scrolling reaches to the end of the listview.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: listviewOptions = {
        onListEnd: (event, inst) => {
        }
    }
}
onNavEnd(event, inst) This event is triggered when hierarchical navigation ends.

Parameters

  • event: Object - The event object has the following properties:
    • level: Number - Level of the hierarchical list.
    • direction: String - The direction of the navigation. It can be 'left' or 'right'.
    • list: Object - The DOM element of the list.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onNavEnd: (event, inst) => {
        }
    }
}
onNavStart(event, inst) This event is triggered when hierarchical navigation starts.

Parameters

  • event: Object - The event object has the following properties:
    • level: Number - Number of levels.
    • direction: String - The direction of the navigation. It can be 'left' or 'right'.
    • list: Object - The DOM element of the list
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onNavStart: (event, inst) => {
        }
    }
}
onSlideEnd(event, inst) This event is triggered when a slide ended.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The index of the item in the list.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSlideEnd: (event, inst) => {
        }
    }
}
onSlideStart(event, inst) This event is triggered when a slide started.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The index of the item in the list.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSlideStart: (event, inst) => {
        }
    }
}
onSort(event, inst) Triggered during sorting, is being fired continuosly when the item is dragged.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The actual index of the item in the list during sort.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSort: (event, inst) => {
        }
    }
}
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

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The actual index of the item in the list during sort.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSortChange: (event, inst) => {
        }
    }
}
onSortEnd(event, inst) Triggered when sorting has stopped.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The final position of the item in the list when the item is dropped.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSortEnd: (event, inst) => {
        }
    }
}
onSortStart(event, inst) Triggered when sorting starts.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The original ordinal position of the dragged element.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSortStart: (event, inst) => {
        }
    }
}
onSortUpdate(event, inst) Triggered when the user stopped sorting and the DOM position has changed.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The position of the item in the list when the sorting stops.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onSortUpdate: (event, inst) => {
        }
    }
}
onStageChange(event, inst) This event is triggered during sliding when the stage changes.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element of the list item.
    • index: Number - The index of the item in the list.
    • stage: Object - The stage of the listview.
  • inst: Object - The instance object of the listview.

Example

export class MyExample {
    settings: any = {
        onStageChange: (event, inst) => {
        }
    }
}

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

  • id: String or Number - The id can be an arbitrary string or number which uniquely identifies the list item.
  • markup: String - Markup of the list item.
  • index (Optional): Number - Index of the list item. If index is omitted, the new item is added to the end of the list.
  • callback (Optional): Function - The callback function is optional and it's called after the add animation is finished.
  • parent (Optional): Object or String - Optionally a parent element can also be specified, if the new element should be added to a sublist. The parent can be a jQuery object of the parent li element or a string pointing to the data-id attribute of the parent li element (if any). If no sublist exists for the specified parent, it will be created. If parent is omitted, the new item will be added to the root list.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.add(1, '<input type="checkbox" data-role="none" /> New Todo');
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

  • func: Function - The function.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.addUndoAction(myFunction);
close(item [, time ]) Closes the given item, if it's actions or stages are opened.

Parameters

  • item: HTMLElement or String - The DOM element or the id of the list item (id must be present in the item's data-id attribute).
  • time (Optional): Number - Time of the animation in milliseconds.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('close', $('#item'));

// With instance
mobiscrollInstance.close($('#item'));
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);
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).

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.endActionTrack();
hideLoading() Hides the loading content. By default the loading content is hidden.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.hideLoading();
move(item, index [, direction ][, callback ]) Moves a list item to another position in the list.

Parameters

  • item: HTMLElement or String - The DOM element or the id of the list item to move.
  • index: Number - The index of the new position.
  • direction (Optional): String - The direction of the remove animation. It can be 'left' or 'right'.
  • callback (Optional): Function - Callback function.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.move($('#item'), 2);
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

  • item: HTMLElement or String - The DOM element or the id of the list 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.navigate(1);
openActions(item, direction [, time ] [, demo ]) Opens the actions of a list item.

Parameters

  • item: HTMLElement or String - The DOM element or the id of the list item (id must be present in the item's data-id attribute).
  • direction: String - Animation direction, can be 'left' or 'right'.
  • time (Optional): Number - Time of the animation in milliseconds.
  • demo (Optional): Boolean - If true, after animation the list item is reverted to its original position.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.openActions($('#item'), 'left', 300, true);
openStage(item, stage [, time ] [, demo ]) Opens the specified stage of a list item.

Parameters

  • item: HTMLElement or String - The DOM element or the id of the list item (id must be present in the item's data-id attribute).
  • stage: String - Defines the stage which will be opened, with the stage object key property.
  • time (Optional): Number - Defines the time of the animation in milliseconds.
  • demo (Optional): Boolean - If true, after animation the list item is reverted to its original position, otherwise an additional tap is required to revert the item.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.openStage($('#item'), 'stage3', 300, true);
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'
});
remove(item [, direction ] [, callback ]) Removes a list item from the list.

Parameters

  • item: HTMLElement or String - The DOM element or the id of the list item.
  • direction (Optional): String - The direction of the remove animation. It can be 'left' or 'right'.
  • callback (Optional): Function - Callback function.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.remove(3);
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);
showLoading() Shows the loading content. By default the loading content is hidden.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.showLoading();
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).

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.startActionTrack();
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!"); });
undo() Last action will be undone.

Example

Methods can be called on an instance. For more details see calling methods 
mobiscrollInstance.undo();

Listview Item Attributes

Name Description
icon Display an icon inside the list item. It needs a font-icon name. Only works if the enhance option is true.
iconAlign Specify icon alignment. It can be "left" or "right", it defaults to "left" if not specified. Only works if the enhance option is true.
selected Sets the initially selected listview items.
type The items can be grouped using the 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:
  • 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'
  • 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.
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:

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/Angular/dist/css/mobiscroll.angular.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.

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
Products
for Javascript
for jQuery
for Angular
for React
View Controls
View Pricing
Download Products
Features
Event calendar & scheduler
Date picker & calendar
FullCalendar alternative
UI for iOS
UI for Ionic
UI for Cordova
Resources
blog
community forum
ui patterns
support & learning
knowledge base
docs
releases
faq
report a bug
Company
about us
contact
customers
reviews
twitter
facebook
Legal
terms & conditions
privacy
cookie policy
eula
© 2023 Acid Media LLC - VAT No. RO19333154     All trademarks © their respective owners. Site uses cookies, you agree to this by browsing it.