Navigation and Tabs in the Onsen UI React Extension

We just released docs for the React components: Check them out!

As seen in the previous blog post we have just announced a React extension for Onsen UI 2.0. It will provide all the Onsen UI custom elements in the form of React components.

In this article we will take a look at how some of the more complex components are used. Since this extension is still in development we would like to get all the feedback we can so we can refine the APIs and iron out all the creases.

Using the extension

We have published the components on npm as react-onsenui. In order to use it you also need to load the core Onsen UI library which is also available on npm as well as, of course, React.

To add Onsen UI and the React extension to your project you can run:

npm install --save-dev onsenui react-onsenui

How you load it depends on your preference. For the people who like browserify you can take a look at this repo on GitHub. It uses browserify to load the libraries and Babel to transpile ES6 and JSX into JavaScript that the browser can understand.

You can also load it in a simple <script> tag. When doing this it’s important that you load all the dependencies in the correct order. The react-onsenui.js file must be loaded after both the React files and the core Onsen UI library since it’s dependent on both.

With a setup like this, using the components is as easy as doing this:

Now we will take a look at how to add advanced navigation using the Navigator and Tabbar components.

Navigator

People who are familiar with Onsen UI knows that we have an element called <ons-navigator> that provides stack based navigation. Using the methods pushPage() and popPage() the app transitions back and forth between views.

Traditionally one would have to use the <ons-template> element to define the content of a page before using the pushPage() method. However, React doesn’t use templates so it wouldn’t make sense for us to expose this kind of API in React. Instead we have taken a look at the Navigator component in React Native. It provides a very powerful API that gives the developer a lot of freedom in managing their page stack.

The component has a method called pushPage(route) which pushes a route object to an internal stack. The route object can be anything. To render the route object into a view the Navigator requires a renderPage function which returns the rendered view. The function must return something that renders into a Page component.

Demo

https://argelius.github.io/react-onsenui-blog-examples/navigator.html

Methods

The component provides a number of methods to control the page stack:

• pushPage(route, options) - Push a route object to the stack and trigger a transition animation. The options object can be used to control the animation.
• popPage(options) - Pops the route object from the top of the stack and transitions to the previous view.
• resetPage(route, options) - Reset the stack to a single route.
• resetPageStack(routes, options) - Reset the stack to an array of routes.

Props

• initialRoute - Define the first route in the stack.
• initialRoutes - Initialize the Navigator with a stack of routes.
• renderPage - Function that takes two arguments:

(route, navigator) => <MyComponent title={route.title} data={route.data} />

The component requires one of either initialRoute or initialRoutes to be specified to initialize the stack. It also requires the renderPage prop so the route objects can be rendered.

Usage

This is the code that is used in the example above. In this code the renderPage function returns the page inline, but you can of course create a component that renders the page to make the function smaller.

Tabbar

Onsen UI provides a number of components for page navigation. In addition to the <ons-navigator> element there is an element called <ons-tabbar> which is used for tab based navigation. Just like the <ons-navigator> it is traditionally used in conjunction with <ons-template> so we decided to provide a special interface for React that doesn’t rely on templates.

Similar to the Navigator this component also requires the developer to provide a function in order for it to work. In this case the function is called renderTabs and has the following structure:

It needs to return an array of objects where each object has the following structure:

{ 
    content: <SomeComponent />, 
    tab: <Ons.Tab ... /> 
}

Demo

https://argelius.github.io/react-onsenui-blog-examples/tabbar.html

Methods

The Tabbar component provides methods to change the active tab and to get the current active tab index.

• setActiveTab(index, options) - Change the active tab to index. The options object can be used to select the transition animation.
• getActiveTabIndex() - Return the current active tab index.

Props

• initialIndex - Specify the tab that is opened initially.
• renderTabs - A function that returns an array of tabs and their content.

Usage

The components are composable

In complex apps there is often a need to combine tabs with stack based navigation. For example, you might want to use a navigator inside one of the tabs or in some cases you would want the tabbar to be one of the pages in the stack.

There is nothing stopping us from combining the Tabbar and the Navigator components in the same app to enable more complex navigation. In the demo below we have an Navigator component where the first page in the stack is an Tabbar component. Using the navigator we can push pages on top of the tabbar.

This is easy to achieve by putting the Tabbar inside the Navigator.

Demo

Onsen UI React Demo

Code

The code for this demo is a bit longer but still pretty simple:

Conclusion

We hope you are as excited as we are about the React extension. As mentioned earlier we would like to get your feedback on the interface. Please share your thoughts in the comments or on the forum.

If you are an Angular 2 developer we are happy to say that we are developing components for Angular 2 as well. We will preview them as well in the coming weeks. Stay tuned!

If you like Onsen UI please leave us a star on our GitHub page.