Looking to learn React Native? Check out React Native Training.

There is a lot you can do with the React Native Navigator. Here, I will try to go over a few examples of what you can do with the Navigator and explain how it all works in depth.

In React Native you have two stable choices as of now for Navigation (only one cross platform) out of the box. There is also the upcoming Navigator Experimental, which is not yet stable, but will be the replacement for the Navigator down the road. If you are interested in learning more about this, check out my tutorials here.

We will focus on the main Navigator component as that is what most questions I have seen pop up are about, and is the cross platform navigator option. We will not talk about NavigatorIOS as it is not currently maintained by the main react native project and is only available for use on iOS.

Here are a few other good navigation options from the community:

Part 1 — Basic Scene Rendering

One thing to understand is that whatever you pass to

navigator.push

is then available in the renderScene method as a property of the route.

Let’s look at an example:

Set up your Navigator like this:

<Navigator

style={{ flex:1 }}

initialRoute={{ name: 'Main' }}

renderScene={ this.renderScene } />

Then, your renderScene method like this:

renderScene(route, navigator) {

if(route.name == 'Main') {

return <Main navigator={navigator} />

}

if(route.name == 'Home') {

return <Home navigator={navigator} />

}

},

When you are ready to push a route, you can to this:

_navigate(){

this.props.navigator.push({

name: 'Home', // Matches route.name

})

}

To call it, simply use:

<TouchableHighlight onPress={ () => this._navigate() }>

<Text>GO To View</Text>

</TouchableHighlight>

Passing Properties

What about passing properties? Let’s look at the above example and add this functionality.

We need to set up an object that we will use to pass these properties. Many people use the name passProps, but this can be whatever name you want. passProps just makes sense as it is actually passing properties. Our navigator component will stay the same. First, let’s edit our renderScene method:

renderScene(route, navigator) {

if(route.name == 'Main') {

return <Main navigator={navigator} {...route.passProps} />

}

if(route.name == 'Home') {

return <Home navigator={navigator} {...route.passProps} />

}

},

Next, our _navigate function:

_navigate(property){

this.props.navigator.push({

name: 'Home',

passProps: {

name: property

}

})

}

And finally let’s pass a property to the navigator:

<TouchableHighlight onPress={ () => this._navigate('Hello World') }>

<Text>GO To View</Text>

</TouchableHighlight>

There is a sample of the above application HERE.

When you have a large application with a lot of routes, the renderScene method we defined above will start to get very large. Next, let’s make the renderScene method more dynamic.

Remember: anything you pass into your navigator.push method will be available as a property on the route.

This means if you call:

this.props.navigator.push({

name: 'chris',

animal: 'dog',

children: 6,

state: 'Arizona'

})

All of these above properties will be available in the renderScene method as a property of the route:

renderScene(route, navigator) {

route.name === 'chris' // true

route.animal === 'cat' // false

route.children === 7 // false

route.state === 'Arizona' // true

}

This way you can do calculations based on what has been passed in:

if(route.animal == 'cat') // do something, render a certain scene or something

Part 2 — Dynamic Scene Rendering

Let’s set up a new renderScene method using another implementation:

renderScene(route, navigator) {

return React.createElement(route.component, { ...this.props, ...route.passProps, route, navigator } )

}

…this.props — spread attributes to ensure any props passed down are available as usual as this.props

…route.passProps — when pushing to a route, allows a passProps property to pass props to next to component

route — route available as a prop on the component

navigator — navigator available as a prop on the component

There is another way to render the above configuration, though we will not be using it in our example it is useful to know about as it has an easier to read syntax if you are not familiar or do not want to use React.createElement:

renderScene(route, navigator) {

let RouteComponent = route.component

return <RouteComponent navigator={navigator} {...route.passProps} />

}

or:

renderScene(route, navigator) {

return <route.component navigator={navigator} {...route.passProps} />

}

As you can see in the first dynamic example above, we are using the React.createElement function to manually create our component definition.

Below is the api for React.createElement in React Native:

ReactElement.createElement(component, [object props], [children …] )

The first argument is the component to render, the second argument is an object containing any props that need to be attached to that component, and the third argument is any children.

To use this, we will call navigator.push like this:

_navigate(name) {

this.props.navigator.push({

component: Home,

passProps: {

name: name

}

})

}

And pass the properties like this:

<TouchableHighlight onPress={ () => this._navigate('SOME NAME') }>

<Text>GO To Home</Text>

</TouchableHighlight>

The component has to be available in the scope of the view for this to work. You can either import the view into the page:

import Home from '../pathtohome'

Or create the component in the same file.

There is an example of the above configuration here.

Part 3 — Scene Configuration

You can control how the navigator renders the scene into the view with the configureScene method on the navigator. The properties available are:

PushFromRight

FloatFromRight

FloatFromLeft

FloatFromBottom

FloatFromBottomAndroid

FadeAndroid

HorizontalSwipeJump

HorizontalSwipeJumpFromRight

VerticalUpSwipeJump

VerticalDownSwipeJump

To implement this, you can set up your navigator with this additional property and attach it to a function:

<Navigator

configureScene={ this.configureScene }

style={{ flex:1 }}

initialRoute={{ component: Main }}

renderScene={ this.renderScene } />

Then, set up your configureScene and pass in one of the above listed configurations:

configureScene(route, routeStack){

return Navigator.SceneConfigs.PushFromRight

}

One interesting way to use this is to check for a route property, then show a modal without having to do a lot of configuration:

configureScene(route, routeStack){

if(route.type === 'Modal') {

return Navigator.SceneConfigs.FloatFromBottom

}

return Navigator.SceneConfigs.PushFromRight

}

Now, we just need to pass the type to the navigator, and set a default type:

_navigate(name, type='Normal') {

this.props.navigator.push({

component: Home,

passProps: {

name: name

},

type: type

})

}

If no type is defined in the _navigate call, then type=’Normal’ will be the default. If anything else is passed as the second argument to _navigate, ‘Normal’ will be replaced.

And we can call the modal like this:

<TouchableHighlight

onPress={ () => this._navigate('HELLO!!', 'Modal') }>

<Text style={ styles.buttonText }>Show Modal</Text>

</TouchableHighlight>

Tada! Here is a working example of Scene Configuration.

Part 4 — Custom Navigation Bar

You may want to have a persistent Navigation Bar in your app. To do this, you need to add another property to the Navigator component called navigationBar and pass in a <Navigator.NavigationBar /> component:

navigationBar={

<Navigator.NavigationBar

style={ styles.nav }

routeMapper={ NavigationBarRouteMapper } />

}

Then we set up the NavigationBarRouteMapper object to configure the nav bar. The NavigationBarRouteMapper takes three function arguments:

LeftButton(route, navigator, index, navState) {

// some component or null

} RightButton(route, navigator, index, navState) {

// some component or null

} Title(route, navigator, index, navState) {

// some component or null

}

We’ve already covered the route and navigator properties, and the same properties will be available in the route and navigator properties here as they are in the renderScene method. index keeps tabs of how far into the route stack you are. index starts at 0 an goes up, so if you want to do calculations based on index you can use this.

We will check if index is zero to show or hide the back button.

We will also check to see if there is a route.onPress function passed in and show or hide a right button with a custom function and text:

var NavigationBarRouteMapper = {

LeftButton(route, navigator, index, navState) {

if(index > 0) {

return (

<TouchableHighlight

underlayColor="transparent"

onPress={() => { if (index > 0) { navigator.pop() } }}>

<Text style={ styles.leftNavButtonText }>Back</Text>

</TouchableHighlight>)

}

else { return null }

},

RightButton(route, navigator, index, navState) {

if (route.onPress) return (

<TouchableHighlight

onPress={ () => route.onPress() }>

<Text style={ styles.rightNavButtonText }>

{ route.rightText || 'Right Button' }

</Text>

</TouchableHighlight>)

},

Title(route, navigator, index, navState) {

return <Text style={ styles.title }>MY APP TITLE</Text>

}

};

Next, let’s set up our .push configuration, create our onPress and pass the onPress method as a property of the route:

onPress() {

alert("YO FROM RIGHT BUTTON")

}



gotoNext() {

this.props.navigator.push({

component: Two,

passProps: {

id: 'MY ID',

},

onPress: this.onPress,

rightText: 'ALERT!'

})

}

Here is what this looks like:

Here is a working example of the navigationBar.

Part 5 — Navigator Methods

So far, we have been using the push method of the navigator:

this.props.navigator.push({

component: SomeComponent

})

But, there are quite a few other methods as well:

getCurrentRoutes() - returns the current list of routes jumpBack() - Jump backward without unmounting the current scene jumpForward() - Jump forward to the next scene in the route stack jumpTo(route) - Transition to an existing scene without unmounting push(route) - Navigate forward to a new scene, squashing any scenes that you couldjumpForward to pop() - Transition back and unmount the current scene replace(route) - Replace the current scene with a new route replaceAtIndex(route, index) - Replace a scene as specified by an index replacePrevious(route) - Replace the previous scene resetTo(route) - Navigate to a new scene and reset route stack immediatelyResetRouteStack(routeStack) - Reset every scene with an array of routes popToRoute(route) - Pop to a particular scene, as specified by its route. All scenes after it will be unmounted popToTop() - Pop to the first scene in the stack, unmounting every other scene

Here is how you would implement some of these other methods:

this.props.navigator.replace({

component: SomeComponent

}) this.props.navigator.pop() this.props.navigator.popToTop() this.props.navigator.resetTo({

component: SomeComponent

})

I’ve set up a project here with these methods implemented.

React Native may be undergoing a future change in the navigation, as there is a proposal to replace the api and functionality. In that case, I will try to do another tutorial on the new navigator functionality in the future if it is released!