react-native Navigator Best Practices Navigator

Example

Navigator is React Native's default navigator. A Navigator component manages a stack of route objects, and provides methods for managing that stack.

<Navigator
  ref={(navigator) => { this.navigator = navigator }}
  initialRoute={{ id: 'route1', title: 'Route 1' }}
  renderScene={this.renderScene.bind(this)}
  configureScene={(route) => Navigator.SceneConfigs.FloatFromRight}
  style={{ flex: 1 }}
  navigationBar={
    // see "Managing the Navigation Bar" below
    <Navigator.NavigationBar routeMapper={this.routeMapper} /> 
  }
/>

Managing the Route Stack

First of all, notice the initialRoute prop. A route is simply a javascript object, and can take whatever shape you want, and have whatever values you want. It's the primary way you'll pass values and methods between components in your navigation stack.

The Navigator knows what to render based on the value returned from its renderScene prop.

renderScene(route, navigator) {
  if (route.id === 'route1') {
    return <ExampleScene navigator={navigator} title={route.title} />; // see below
  } else if (route.id === 'route2') {
    return <ExampleScene navigator={navigator} title={route.title} />; // see below
  }
}

Let's imagine an implementation of ExampleScene in this example:

function ExampleScene(props) {

  function forward() {
    // this route object will passed along to our `renderScene` function we defined above.
    props.navigator.push({ id: 'route2', title: 'Route 2' });
  }

  function back() {
    // `pop` simply pops one route object off the `Navigator`'s stack
    props.navigator.pop();
  }

  return (
    <View>
      <Text>{props.title}</Text>
      <TouchableOpacity onPress={forward}>
        <Text>Go forward!</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={back}>
        <Text>Go Back!</Text>
      </TouchableOpacity>
    </View>
  );
}

Configuring the Navigator

You can configure the Navigator's transitions with the configureScene prop. This is a function that's passed the route object, and needs to return a configuration object. These are the available configuration objects:

• Navigator.SceneConfigs.PushFromRight (default)
• Navigator.SceneConfigs.FloatFromRight
• Navigator.SceneConfigs.FloatFromLeft
• Navigator.SceneConfigs.FloatFromBottom
• Navigator.SceneConfigs.FloatFromBottomAndroid
• Navigator.SceneConfigs.FadeAndroid
• Navigator.SceneConfigs.HorizontalSwipeJump
• Navigator.SceneConfigs.HorizontalSwipeJumpFromRight
• Navigator.SceneConfigs.VerticalUpSwipeJump
• Navigator.SceneConfigs.VerticalDownSwipeJump

You can return one of these objects without modification, or you can modify the configuration object to customize the navigation transitions. For example, to modify the edge hit width to more closely emulate the iOS UINavigationController's interactivePopGestureRecognizer:

configureScene={(route) => {
  return {
    ...Navigator.SceneConfigs.FloatFromRight,
    gestures: {
      pop: {
        ...Navigator.SceneConfigs.FloatFromRight.gestures.pop,
        edgeHitWidth: Dimensions.get('window').width / 2,
      },
    },
  };
}}

Managing the NavigationBar

The Navigator component comes with a navigationBar prop, which can theoretically take any properly configured React component. But the most common implementation uses the default Navigator.NavigationBar. This takes a routeMapper prop that you can use to configure the appearance of the navigation bar based on the route.

A routeMapper is a regular javascript object with three functions: Title, RightButton, and LeftButton. For example:

const routeMapper = {

  LeftButton(route, navigator, index, navState) {
    if (index === 0) {
      return null;
    }

    return (
      <TouchableOpacity
        onPress={() => navigator.pop()}
        style={styles.navBarLeftButton}
      >
        <Text>Back</Text>
      </TouchableOpacity>
    );
  },

  RightButton(route, navigator, index, navState) {
    return (
      <TouchableOpacity
        onPress={route.handleRightButtonClick}
        style={styles.navBarRightButton}
      >
        <Text>Next</Text>
      </TouchableOpacity>
   );
  },

  Title(route, navigator, index, navState) {
    return (
      <Text>
        {route.title}
      </Text>
    );
  },
};

See more

For more detailed documentation of each prop, see the the official React Native Documentation for Navigator, and the React Native guide on Using Navigators.