React Native Navigator — Navigating Like A Pro in React Native

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:

  1. ExNavigator by Exponent

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 routesjumpBack() - Jump backward without unmounting the current scenejumpForward() - Jump forward to the next scene in the route stackjumpTo(route) - Transition to an existing scene without unmountingpush(route) - Navigate forward to a new scene, squashing any scenes that you couldjumpForward topop() - Transition back and unmount the current scenereplace(route) - Replace the current scene with a new routereplaceAtIndex(route, index) - Replace a scene as specified by an indexreplacePrevious(route) - Replace the previous sceneresetTo(route) - Navigate to a new scene and reset route stackimmediatelyResetRouteStack(routeStack) - Reset every scene with an array of routespopToRoute(route) - Pop to a particular scene, as specified by its route. All scenes after it will be unmountedpopToTop() - 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

Also, check out my book, React Native in Action now available from Manning Publications

If you enjoyed this article, please recommend and share it! Thanks for your time

React Native Training

Stories and tutorials for developers interested in React Native

Nader Dabit

Written by

Developer Advocate at AWS Mobile — Specializing in Teaching and Building React & React Native — http://reactnative.training https://aws.amazon.com/mobile

React Native Training

Stories and tutorials for developers interested in React Native