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.

Basic usage

The Mobiscroll Navigation control has the following react components: <mobiscroll.BottomNav />, <mobiscroll.HamburgerNav />, <mobiscroll.TabNav /> and <mobiscroll.NavItem /> as the child component of the former.

While the navigation components can be used with the react router, it is not a requirement. If you are not using the react router in your app, you can skip the following section and go to the simple examples

Using with react router

The navigation components can be used with the react-router packages. The <NavItem /> component supports the same props the react router package's <Link /> component has.

Version 5 and above of React Router package is only supported from Mobiscroll Version 4.8.2 and upwards.

To work with the react-router package, Mobiscroll needs to be configured! The following section describes how to configure the navigation component:

Configuration

The setup of the Mobiscroll Navigation component with React Router can be done by calling the setupReactRouter function and providing the Route and withRouter parameters from the react-router-dom. Here's an example:

import { Route, withRouter } from 'react-router-dom';
import mobiscroll from 'path-to-mobiscroll';
    
// setup the React Router with Mobiscroll
mobiscroll.setupReactRouter(Route, withRouter);

After the configuration the navigation component will be aware of the parent Router, and will change it's selected state based on the current location and the to prop passed to it's items.

A simple example for rendering different components, using the url hash:

Simple React Router example:
import { Route, withRouter, HashRouter as Router, Switch } from 'react-router-dom';
import mobiscroll from 'path-to-mobiscroll';
mobiscroll.setupReactRouter(Route, withRouter);

const News = () => <div>News</div>;
const Search = () => <div>Search</div>;
const Profile = () => <div>My Profile</div>;

const App = (props) => {
    return <Router>
         <mobiscroll.BottomNav>
             <mobiscroll.NavItem to="/news">News</mobiscroll.NavItem>
             <mobiscroll.NavItem to="/search">Search</mobiscroll.NavItem>
             <mobiscroll.NavItem to="/profile">Profile</mobiscroll.NavItem>
         </mobiscroll.BottomNav>
         <Switch>
             <Route path="/news" component={News} />
             <Route path="/search" component={Search} />
             <Route path="/profile" component={Profile} />
         </Switch>
    </Router>;
}

Using the NavItems

The <mobiscroll.NavItem/> works the same way as a NavLink component from the React Router package does. It applies the active styling for itself based on the location match automatically. It also supports most of the props that the NavLink component does, to provide a fully customizable navigation. Here's a complete list of the supported props.

The most important prop of the NavItem is the to prop. When the NavItem is pressed, it will navigate to the path provided by it.

When the location matches with the NavItems to prop, it is rendered as active. The exact prop can also be usefull, when the location contains multiple segments.
For example:
When the to="/video" is used, it will also match "/video/search" and "/feed/video/funny".
Sometimes this behavior is not wanted, so providing the exact prop to the NavItem will make it match only when the paths are matched exactly.

The below example when rendered, will redirect from the "/" path to the "/books" path, so the Books component will be rendered just after.

The exact prop will ensure that the redirect route won't be triggered by the other paths that contain the "/" character.

Default a tab with the redirect route
import { Route, withRouter, HashRouter as Router, Switch, Redirect } from 'react-router-dom'; // import the Redirect route as well
import mobiscroll from 'path-to-mobiscroll';
mobiscroll.setupReactRouter(Route, withRouter);

const App = (props) => {
    return <Router>
         <mobiscroll.TabNav display="top">
             <mobiscroll.NavItem to="/books">Books</mobiscroll.NavItem>
             <mobiscroll.NavItem to="/music">Music</mobiscroll.NavItem>
         </mobiscroll.TabNav>
         <Switch>
             <Route path="/books" component={Books} />
             <Route path="/music" component={Music} />
             <Redirect path="/" exact to="/books" />
         </Switch>
    </Router>;
}

Simple examples

Here are a few examples without the React Router
<mobiscroll.TabNav display="inline">
    <mobiscroll.NavItem icon="connection"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="location"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="volume-medium"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="fa-rotate-left"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="ion-bluetooth"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="cogs"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="user4"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="download"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="foundation-minus-circle"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="fa-leaf"></mobiscroll.NavItem>
    <mobiscroll.NavItem icon="ion-android-system-windows"></mobiscroll.NavItem>
</mobiscroll.TabNav>

<mobiscroll.HamburgerNav>
    <mobiscroll.NavItem icon="connection">Wi-Fi</mobiscroll.NavItem>
    <mobiscroll.NavItem disabled={true} icon="location">Location</mobiscroll.NavItem>
    <mobiscroll.NavItem icon="volume-medium">Sound</mobiscroll.NavItem>
    <mobiscroll.NavItem selected={true} icon="fa-rotate-left">Rotation</mobiscroll.NavItem>
    <mobiscroll.NavItem icon="ion-bluetooth">Bluetooth</mobiscroll.NavItem>
    <mobiscroll.NavItem icon="cogs">Settings</mobiscroll.NavItem>
    <mobiscroll.NavItem icon="user4">Reading</mobiscroll.NavItem>
    <mobiscroll.NavItem icon="download">Data</mobiscroll.NavItem>
</mobiscroll.HamburgerNav>
Generating items dynamically
/* in your component */
constructor(props) {
    super(props);
    this.state = { selected: 'home' };
}

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

items = [
    {id: 'home', text: 'Home', disabled: false, icon: 'home', badge: null },
    {id: 'feed', text: 'Feed', disabled: true, icon: 'pencil', badge: '2' },
    {id: 'settings', text: 'Settings', disabled: false, icon: 'user4', badge: null }
];

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

NavItem props that are inherited from the NavLink component from the React Router Package.

Prop Type Description
to string or object Sets the location the item navigates to. When the NavItem is pressed, it will navigate to the path provided by this prop.
Also the NavItem's active style will be determined based on this prop.
When an object is passed, it can have the following properties:
  • pathname: the path to navigate to
  • search: a string representation of the query parameters
  • hash: a hash to put in the URL
  • state: a state to persist to the location
Examples:
<NavItem to="/home">Home<NavItem>
<NavItem to={{ pathname: "/news", search: "?order=desc" }}>News<NavItem>
replace bool When true is passed, the navigation will replace the current entry in the history stack instead of adding a new one.
isActive func A function to add extra logic for determining whether the nav item is selected (active). It receives a match and location parameters and should return a bool value.
location string or object The isActive function compares the current history location. To compare to a different location, a location can be passed.
exact bool When true, the NavItem will be active only if the location path is matched exactly
strict bool When true, the trailing slash of the location will be taken into consideration when determining selected state
sensitive bool When true, the location matching will be case sensitive
Prop Type Description
selected bool Sets the item selected state
disabled bool Sets the item disabled state
icon string Sets the item icon
badge string Sets the item badge
id string Sets the item id

<mobiscroll.BottomNav />
<mobiscroll.HamburgerNav />
<mobiscroll.TabNav /> props

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.
mousewheel Boolean false Enables mousewheel / touchpad scroll.
paging Boolean false Scroll one page at a time. The page size will be the width of the container.
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' - iOS theme
  • 'ios-dark' - iOS dark theme (deprecated)
  • 'material' - Material theme
  • 'material-dark' - Material dark theme (deprecated)
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll dark theme (deprecated)
  • 'windows' - Windows theme
  • 'windows-dark' - Windows dark theme (deprecated)
It's possible to modify theme colors or create custom themes.
Starting from v4.9.0 setting directly the dark version of the theme is deprecated. Use the themeVariant setting instead to control the light / dark appearance of the theme.
Make sure that the theme you set is included in the downloaded package.
themeVariant String undefined Controls which variant of the theme will be used (light or dark).

Possible values:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' - Detect the preferred system theme on devices where this is supported.

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

To use the setting with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with '-dark', e.g.: 'my-theme' and 'my-theme-dark'.
The setting will not have any effect if the theme setting explicitly sets the dark version of a theme, e.g. theme: 'ios-dark'.
threshold Number 10 Minimum horizontal movement in pixels before the scrolling starts.
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 'top'.
  • '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'.

Events

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

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

<mobiscroll.Navigation
    onGestureStart={function (event, inst) {
    }}
/>
onInit(event, inst) Triggered when the component is initialized.

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

<mobiscroll.Navigation
    onMarkupReady={function (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

<mobiscroll.BottomNav
    onMenuHide={function (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

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

Parameters

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

Example

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

Methods

Name Description
deselect(item) Deselects the specified item.

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getInst();
navigate(item [, toggle ]) Scrolls the 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 and triggers the onItemTap event. If undefined, defaults to true in single select mode and to false in multiselect mode.

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Parameters

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

Example

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

Example

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

Parameters

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

Example

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

Data attributes

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

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

See the full list of available icons here.

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