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:
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 NavItem
s
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 NavItem
s 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.
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
<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>
/* 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>;
}
<mobiscroll.NavItem />
props
NavItem props that are inherited from the NavLink component
from the React Router Package.
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
For many more examples - simple and complex use-cases - check out the navigation demos for react.
Options
Name | Type | Default value | Description |
---|---|---|---|
context | String, HTMLElement | 'body' |
The DOM element in which the component 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:
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:
|
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. |
responsive | Object | undefined |
Specify different settings for different container widths, in a form of an object,
where the keys are the name of the breakpoints, and the values are objects containing
the settings for the given breakpoint.
The available width is queried from the container element of the component and not the browsers viewport like in css media queries
There are five predefined breakpoints:
breakpoint
property specifying the min-width in pixels.
Example:
|
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 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' .
|
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:
|
Events
Name | Description | |
---|---|---|
onAnimationEnd(event, inst) | Gets fired when an autonomous scrolling/sliding ends.
Parameters
Example
|
|
onAnimationStart(event, inst) | Gets fired when an autonomous scrolling/sliding is starts.
Parameters
Example
|
|
onGestureEnd(event, inst) | Gets fired when the user ends the scrolling gesture.
Parameters
Example
|
|
onGestureStart(event, inst) | Gets fired when the user ends the scrolling(swiping) gesture.
Parameters
Example
|
|
onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example
|
|
onItemTap(event, inst) |
Triggered when an item is tapped.
Parameters
Example
|
|
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
Example
|
|
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
Example
|
|
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
Example
|
|
onMove(event, inst) | Gets fired when an autonomous scrolling/sliding ends.
Parameters
Example
|
Methods
Name | Description | |
---|---|---|
deselect(item) | Deselects the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
disable(item) |
Disables the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
enable(item) |
Enables the specified item
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
navigate(item [, toggle ] [, animTime]) |
Scrolls the navigation to the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
next([toggle]) | Scrolls the navigation to the next 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
|
|
prev([toggle]) | Scrolls the navigation to the previous item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
refresh() |
Recalculate dimensions needed for scrolling.
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
|
|
setBadge(item, content) | Sets the badge of the navigation item.
Parameters
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
|
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:
|
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: You can use the icons anywhere in your app using thembsc-ic mbsc-ic-{iconName} classes, e.g.:
|
data-selected | If true the navigation item will be selected. |
Customizing the appearance
While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:
- Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
- Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
- Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.
Override the Sass Color Variables
A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.
Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well,
while still using platform specific themes (e.g. ios
on iOS devices, material
on Android devices, and mobiscroll
on desktop).
You can override the accent color for every theme:
$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;
@import "~@mobiscroll/React/dist/css/mobiscroll.react.scss"
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-nav-background-light | Sets the background color of the navigation |
$mbsc-nav-background-dark | |
$mbsc-nav-text-light | Sets the text color of the navigation |
$mbsc-nav-text-dark | |
$mbsc-nav-accent-light | Sets the accent color of the navigation |
$mbsc-nav-accent-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-nav-background | #f7f7f7 | The navigation background color |
$mbsc-ios-nav-text | #878787 | The navigation text color |
$mbsc-ios-nav-accent | #007bff | The navigation accent color |
iOS Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-ios-dark-nav-background | #000000 | The navigation background color |
$mbsc-ios-dark-nav-text | #ababab | The navigation text color |
$mbsc-ios-dark-nav-accent | #ff8400 | The navigation accent color |

Windows theme
Variable name | Default value | Description |
---|---|---|
$mbsc-windows-nav-background | #f2f2f2 | The navigation background color |
$mbsc-windows-nav-text | #262626 | The navigation text color |
$mbsc-windows-nav-accent | #0078d7 | The navigation accent color |
Windows Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-windows-dark-nav-background | #191919 | The navigation background color |
$mbsc-windows-dark-nav-text | #ffffff | The navigation text color |
$mbsc-windows-dark-nav-accent | #0078d7 | The navigation accent color |

Material theme
Variable name | Default value | Description |
---|---|---|
$mbsc-material-nav-background | #eeeeee | The navigation background color |
$mbsc-material-nav-text | #5b5b5b | The navigation text color |
$mbsc-material-nav-accent | #009688 | The navigation accent color |
Material Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-material-dark-nav-background | #303030 | The navigation background color |
$mbsc-material-dark-nav-text | #c2c2c2 | The navigation text color |
$mbsc-material-dark-nav-accent | #81ccc4 | The navigation accent color |

Mobiscroll theme
Variable name | Default value | Description |
---|---|---|
$mbsc-mobiscroll-nav-background | #f7f7f7 | The navigation background color |
$mbsc-mobiscroll-nav-text | #454545 | The navigation text color |
$mbsc-mobiscroll-nav-accent | #4eccc4 | The navigation accent color |
Mobiscroll Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-mobiscroll-dark-nav-background | #253238 | The navigation background color |
$mbsc-mobiscroll-dark-nav-text | #f7f7f7 | The navigation text color |
$mbsc-mobiscroll-dark-nav-accent | #4fccc4 | The navigation accent color |
