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 choices as of now for Navigation (only one cross platform) out of the box, as well as the ExNavigator from Exponent. 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. But definitely check out ExNavigator by Exponent, it is also really good.
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 could 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!
My Name is Nader Dabit . I am a developer at School Status where we help educators make smart instructional decisions by providing all their data in one place. Check us out @schoolstatusapp.
If you like React Native, checkout out our podcast — React Native Radio onDevchat.tv