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

Navigation

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

Simple navigation

The Mobiscroll Navigation components can be used along with angular's built in routerLink directive.

When the routerLink is placed on a Mobiscroll Nav Item component, it will automatically become active, when the associated route is activated.

Configuration

To turn on the automatic route recognition, the angular Router needs to be passed to the MbscModule. In the root app.module.ts file, after the mobiscroll module is imported, the forRoot method must be called and passed a configuration object. Here's an example:

For complete development packages, where the uncompressed source code is set up to the project, the MbscNavigationModule can be used the same way as the MbscModule.
It makes possible to only import the module that is truly needed.

Configuring the MbscModule in the root app.module.ts
import { MbscModule } from 'path to library';
import { Router } from '@angular/router';

@NgModule({
  imports:      [ BrowserModule, MbscModule.forRoot({ angularRouter: Router }), FormsModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
export class AppModule { }

Here are some examples using the mobiscroll navigation components with the routerLink directive:

Examples
<!-- Navigation rendered at the bottom -->
<mbsc-bottom-nav>
    <mbsc-nav-item routerLink="home">Home</mbsc-nav-item>
    <mbsc-nav-item routerLink="feed" badge="2">Feed</mbsc-nav-item>
    <mbsc-nav-item routerLink="settings">Settings</mbsc-nav-item>
</mbsc-bottom-nav>

<!-- Hamburger navigation menu -->
<mbsc-hamburger-nav>
    <mbsc-nav-item [routerLink]="['home']">Home</mbsc-nav-item>
    <mbsc-nav-item [routerLink]="['feed']">Feed</mbsc-nav-item>
    <mbsc-nav-item [routerLink]="['settings']">Settings</mbsc-nav-item>
</mbsc-hamburger-nav>

<!-- Tab navigation menu -->
<mbsc-tab-nav>
    <mbsc-nav-item [routerLink]="['home', {outlets: { message: null}}]">Home</mbsc-nav-item>
    <mbsc-nav-item [routerLink]="['feed', {outlets: { message: ['empty'] }}]">Feed</mbsc-nav-item>
    <mbsc-nav-item [routerLink]="['settings', {outlets: { message: null }}]">Settings</mbsc-nav-item>
</mbsc-tab-nav>

Custom use-cases

The navigation components can be used without the angular router by binding the selected attribute to any expression. Here are a few examples:

Examples without angular router
<!-- Navigation rendered at the bottom -->
<mbsc-bottom-nav>
    <mbsc-nav-item [selected]="currentNav == 'home'">Home</mbsc-nav-item>
    <mbsc-nav-item [selected]="currentNav == 'feed'" badge="2">Feed</mbsc-nav-item>
    <mbsc-nav-item [selected]="currentNav == 'settings'">Settings</mbsc-nav-item>
</mbsc-bottom-nav>

<!-- Hamburger navigation menu -->
<mbsc-hamburger-nav>
    <mbsc-nav-item [selected]="currentNav == 'home'">Home</mbsc-nav-item>
    <mbsc-nav-item [selected]="currentNav == 'feed'">Feed</mbsc-nav-item>
    <mbsc-nav-item [selected]="currentNav == 'settings'">Settings</mbsc-nav-item>
</mbsc-hamburger-nav>

<!-- Tab navigation menu -->
<mbsc-tab-nav>
    <mbsc-nav-item id="home" [selected]="currentNav == 'home'">Home</mbsc-nav-item>
    <mbsc-nav-item id="feed" [selected]="currentNav == 'feed'">Feed</mbsc-nav-item>
    <mbsc-nav-item id="settings" [selected]="currentNav == 'settings'">Settings</mbsc-nav-item>
</mbsc-tab-nav>
Passing simple options inline:
<!-- Navigation rendered inline -->
<mbsc-bottom-nav display="inline">
    <mbsc-nav-item>Home</mbsc-nav-item>
    <mbsc-nav-item>Feed</mbsc-nav-item>
    <mbsc-nav-item>Settings</mbsc-nav-item>
</mbsc-bottom-nav>

<!-- custom menu text -->
<mbsc-hamburger-nav menuText="Main menu">
    <mbsc-nav-item>Home</mbsc-nav-item>
    <mbsc-nav-item>Feed</mbsc-nav-item>
    <mbsc-nav-item>Settings</mbsc-nav-item>
</mbsc-hamburger-nav>

<!-- fixed item width -->
<mbsc-tab-nav display="inline" itemWidth="100">
    <mbsc-nav-item>Home</mbsc-nav-item>
    <mbsc-nav-item>Feed</mbsc-nav-item>
    <mbsc-nav-item>Settings</mbsc-nav-item>
</mbsc-tab-nav>

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-bottom-nav (onItemTap)="itemTapped()">
    ...
</mbsc-bottom-nav>

<!-- with default parameters -->
<mbsc-bottom-nav (onItemTap)="withDefaultEvent($event)">
    ...
</mbsc-bottom-nav>

<!-- with additional parameters -->
<mbsc-bottom-nav (onItemTap)="withAdditionalEvent($event, 'myAddition')">
    ...
</mbsc-bottom-nav>
export class MyExampleClass {
    // simple handler without any parameters
    itemTapped() {
        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 navigation control instance
    }

    // event handler with additional parameters
    withAdditionalEvent(event: any, addition: string) {
        console.log(addition); // prints 'myAddition'
    }
}
Customizing items
<!-- theme, icons and disabled state -->
<mbsc-bottom-nav theme="ios">
    <mbsc-nav-item icon="home">Home</mbsc-nav-item>
    <mbsc-nav-item icon="user4" [disabled]="!userLoggedIn">Feed</mbsc-nav-item>
    <mbsc-nav-item icon="pencil">Settings</mbsc-nav-item>
</mbsc-bottom-nav>

<!-- fixed item width -->
<mbsc-tab-nav itemWidth="100">
    <mbsc-nav-item>Home</mbsc-nav-item>
    <mbsc-nav-item>Feed</mbsc-nav-item>
    <mbsc-nav-item>Settings</mbsc-nav-item>
</mbsc-tab-nav>

<mbsc-tab-nav display="top">
    <mbsc-nav-item id="home" [selected]="currentNav == 'home'" (click)="currentNav = 'home'">Home</mbsc-nav-item>
    <mbsc-nav-item id="feed" [selected]="currentNav == 'feed'" (click)="currentNav = 'feed'">Feed</mbsc-nav-item>
    <mbsc-nav-item id="settings" [selected]="currentNav == 'settings'" (click)="currentNav = 'settings'">Settings</mbsc-nav-item>
</mbsc-tab-nav>
Rendering items dynamically
@Component({
    selector: 'my-example',
    template: `<mbsc-bottom-nav display="inline">
        <mbsc-nav-item *ngFor="let item of items" [badge]="item.badge" [(selected)]="item.selected" [disabled]="item.disabled" [icon]="item.icon">{{item.text}}</mbsc-nav-item>
    </mbsc-bottom-nav>`
})
export class MyExampleComponent {
    items = [{
        selected: true,
        icon: 'home',
        text: 'Home'
    }, {
        selected: false,
        icon: 'pencil',
        text: 'Feed',
        badge: '5'
    }, {
        selected: false,
        disabled: true,
        icon: 'office',
        text: 'Office'
    }];
}

Using with Ionic

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

Modules

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

Components

Component Description
<mbsc-bottom-nav> Bottom navigation component
<mbsc-tab-nav> Tab navigation component
<mbsc-hamburger-nav> Hamburger navigation component
<mbsc-nav-item> Navigation item component

Attributes

Attributes for the items

Attribute Data type Description
[(selected)] boolean Attribute used to determin if the navigation item is selected or not
[disabled] boolean Attribute used to determin if the navigation item is disabled or not
[icon] string Used to pass the name of the icon
[badge] string Used to set the badge to the nav-item
[id] string Used to pass an id to the item. Needed when navigation occurs programatically.

Attributes for the components

Attribute Data type Description
[options] MbscNavigationOptions Attribute used to pass the options as one object

The following options can be used as attributes to customize the navigation components further:

Options

Name Type Default value Description
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
display String depends on the type setting Controls the position of the navigation. Possible values:
  • 'inline' - Stay in the normal document flow.
  • 'top' - Fixed to top.
  • 'bottom' - Fixed to bottom.
Tab navigation defaults to top.
Bottom navigation defaults to bottom.
Hamburger navigation defaults to inline.
itemWidth Number undefined If layout is 'fixed', it represents the exact witdh of the items in pixels, otherwise the minimum width of the items, and the items will be stretched to fill the container width.
layout String
Number
'liquid' Possible values:
  • 'liquid' - The number of displayed items will be calculated from the itemWidth option, if specified, items will be stretched to fill the container width.
  • 'fixed' - Item width will be defined by the content inside, or the itemWidth option, if specified.
  • integer - Number of items to display. If itemWidth is also specified, it will represent the maximum number of items to display.
paging Boolean false Scroll one page at a time. The page size will be the width of the container.
snap Boolean false When the navigation is scrolled it snaps to the edge of the last visible item which is at the opposite direction of the scroll.
theme String undefined Sets the visual appearance of the component.

If it is 'auto' or undefined, the theme will automatically be chosen based on the platform. If the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'bootstrap' - Bootstrap themes
  • 'ios' - new iOS 7, 8, 9 theme
  • 'material' - Material theme (Android 5.x)
  • 'material-dark' - Material dark theme (Android 5.x)
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll Dark theme
  • 'windows' - Windows theme
  • 'windows-dark' - Windows theme (dark version)
It's possible to create custom themes in css by prefixing any css class used in the navigation markup with the theme name and the 'mbsc' prefix, e.g.: .mbsc-my-theme .dwwr { /* My CSS */ }, and set the theme option to 'my-theme'
Make sure that the theme you set is included in the downloaded package.
threshold Number 10 Minimum horizontal movement in pixels before the scrolling starts.
type String 'bottom' Define the appearance and functionality of the navigation. Possible values:
  • 'tab' - Variant B styling. Displays as many items as possible and makes the navigation scrollable. The default display mode is 'inline'.
  • 'bottom' - Variant A styling. Displays as many items as possible and renders the show more menu if needed. The default display mode is 'bottom'.
  • 'hamburger' - Variant A styling. Displays items in a hamburger menu. The default display mode is 'inline'.

Setting options runtime (changing 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-navigation #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. readonly, calendar marked days).

    Example
    import { ViewChild } from '@angular/core';
    @Component({
        selector: 'my-example',
        template: `
            <input mbsc-navigation #myVariable="mobiscroll" [mbsc-options]="myOptions"/>
            <button (click)="changeOptions()">Change readonly</button>
        `
    })
    export class MyExample {
        @ViewChild('myVariable') 
        myRef: any;
    
        // get instance and modify a setting
        changeOptions() {
            this.myRef.instance.settings.readonly = true;
        }
        
        // Modify settings in an event
        myOptions: any = {
            onBeforeShow: (event, inst) => {
                inst.settings.readonly = 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
onAnimationEnd(event, inst) Gets fired when an autonomous scrolling/sliding ends.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onAnimationEnd: (event, inst) => {
        }
    }
}
onAnimationStart(event, inst) Gets fired when an autonomous scrolling/sliding is starts.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onAnimationStart: (event, inst) => {
        }
    }
}
onGestureEnd(event, inst) Gets fired when the user ends the scrolling gesture.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onGestureEnd: (event, inst) => {
        }
    }
}
onGestureStart(event, inst) Gets fired when the user ends the scrolling(swiping) gesture.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onGestureStart: (event, inst) => {
        }
    }
}
onInit(event, inst) Triggered when the component is initialized.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onInit: (event, inst) => {
        }
    }
}
onItemTap(event, inst) Triggered when an item is tapped.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onItemTap: (event, inst) => {
        }
    }
}
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onMarkupReady: (event, inst) => {
        }
    }
}
onMenuHide(event, inst) Gets fired when the popup containing the menu items closes. Close can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • target: the DOM element which was tapped to open the menu.
    • menu: the widget instance of the menu popup.
  • inst: Object - The instance object of the navigation component.

Example

export class MyExample {
    settings: any = {
        onMenuHide: (event, inst) => {
        }
    }
}
onMenuShow(event, inst) Gets fired when the popup containing the menu items is shown. Show can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • target: the DOM element which was tapped to open the menu.
    • menu: the widget instance of the menu popup.
  • inst: Object - The instance object of the navigation component.

Example

export class MyExample {
    settings: any = {
        onMenuShow: (event, inst) => {
        }
    }
}
onMove(event, inst) Gets fired when an autonomous scrolling/sliding ends.

Parameters

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

Example

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

Methods

Name Description
deselect(item) Deselects the specified item.

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Returns: Object

  • The object instance.

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Example

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

Parameters

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

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.select(2);
setBadge(item, content) Sets the badge of the navigation 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).
  • content: String - Content of the badge.

Example

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

Parameters

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

Example

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

Localization

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

Navigation item attributes

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

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

See the full list of available icons here.

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