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:
<!-- 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:
<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.
<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.
<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.
<!-- 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:
<!-- 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.
<!-- 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:
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.:
A sample stage array:
A sample stage object:
|
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. |
Setting options dynamically
There are two ways to modify options after initalization
-
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 changeimport { 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' }); } }
-
Modify directly the
settings
object.
Useful when changing dynamic settings, which do not need redraw (e.g. vibrate, calendar marked days).
Exampleimport { 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
this
reference.inst
parameter is passed as a property to the event.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
|
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:
|
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/Angular/dist/css/mobiscroll.angular.scss"
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 |
