React NativeNavigation # | Edit on GitHub |
Mobile apps rarely consist of just one screen or scene. As soon as you add a second scene to your app, you will have to take into consideration how the user will navigate from one scene to the other.
Navigators in React Native allow you to push and pop scenes in a master/detail stack, or to pop up modal scenes. Navigators handle the transitions between scenes, and also maintain the navigational state of your application.
If you are just getting started with React Native, you will probably want to start with the Navigator component.
Navigator #
Navigator is a cross-platform implementation of a navigation stack, so it works on both iOS and Android. It is easy to customize and includes simple navigation bars.
Navigation # | Edit on GitHub |
Mobile apps rarely consist of just one scene (another word for screen). As soon as you add a second scene to your app, you will have to take into consideration how the user will navigate from one scene to the other.
You can use navigators to transition between multiple scenes. These transitions can be typical side-to-side animations down a master/detail stack, or vertical modal popups.
Navigator #
React Native has several built-in navigation components, but for your first app you will probably want to use Navigator. It provides a JavaScript implementation of a navigation stack, so it works on both iOS and Android and is easy to customize.
Something you will encounter a lot when dealing with navigation is the concept of routes. A route is an object that contains information about a scene. It is used to provide all the context that the navigator's renderScene function needs to render a scene. A basic Navigator implementation may look like this:
Something you will encounter a lot when dealing with navigation is the concept of routes. A route is an object that contains information about a scene. It is used to provide all the context the renderScene function needs to render a scene.
The push and pop functions provided by Navigator can be used to push and pop routes into the navigation stack. A more complete example that demonstrates the pushing and popping of routes could therefore look something like this:
The above example will display a single scene, but in order to push a new scene onto screen you will need to learn about push and pop. These two methods are provided by the navigator object that is passed to your renderScene function. They can be used, as you may have realized, to push and pop routes into your navigation stack.
A more complete example that demonstrates the pushing and popping of routes could therefore look something like this:
In this example, the MyScene component is passed the title of the current route via the title prop. It displays two tappable components that call the onForward and onBack functions passed through its props, which in turn will call navigator.push() and navigator.pop() as needed.
While this is a very basic example, it can easily be adapted to render an entirely different component based on the route that is passed to the renderScene function. Navigator will push new scenes from the right by default, and you can control this behavior by using the configureScene function. Check out the Navigator API reference to learn more.
NavigatorIOS #
If you are targeting iOS only, you may also want to consider using NavigatorIOS. It looks and feels just like UINavigationController, because it is actually built on top of it.
In this example, the MyScene component is passed the title of the current route via the title prop. It displays two tappable components that call the onForward and onBack functions passed through its props, which in turn will call navigator.push() and navigator.pop() as needed.
While this is a very basic example, it can easily be adapted to render an entirely different component based on the route that is passed to the renderScene function. Navigator will push new scenes from the right by default, and you can control this behavior by using the configureScene function. You can also configure a navigation bar through the navigationBar prop.
Check out the Navigator API reference for more code samples.
NavigatorIOS #
If you are targeting iOS only, you may also want to consider using NavigatorIOS. It looks and feels just like UINavigationController, because it is actually built on top of it.
Just like Navigator, it it uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the component key in the route, and any props that should be passed to this component can be specified in passProps. A navigator object is automatically passed as a prop to the component, allowing you to call push and pop as needed.
Check out the NavigatorIOS reference docs to learn more about this component.
Just like Navigator, NavigatorIOS uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the component key in the route, and any props that should be passed to this component can be specified in passProps. A "navigator" object is automatically passed as a prop to the component, allowing you to call push and pop as needed.
As NavigatorIOS leverages native UIKit navigation, it will automatically render a navigation bar with a back button and title.
Check out the NavigatorIOS reference docs to learn more about this component.
You may also want to check out react-native-navigation, a component that aims to provide native navigation on both iOS and Android.
NavigationExperimental #
Navigator and NavigatorIOS are both stateful components. If your app has multiple of these, it can become tricky to coordinate navigation transitions between them. NavigationExperimental provides a different approach to navigation, allowing any view to act as a navigation view and using reducers to manipulate state at a top-level object. It is bleeding edge as the name implies, but you might want to check it out if you are craving greater control over your app's navigation.
You can import NavigationExperimental like any other component in React Native. Once you have that, you can deconstruct any additional components from NavigationExperimental that you may find useful. Since I am feeling like building navigation stacks today, I'll go ahead and pick out NavigationCardStack and NavigationStateUtils.
As I said earlier, NavigationExperimental takes a different approach than Navigator and NavigatorIOS. Using it to build a navigation stack requires a few more steps than the stateful components, but the payoff is worth it.
Step 1. Define Initial State and Top Level Component #
Create a new component for your application. This will be the top-level object, so we will define the initial state here. The navigation state will be defined in the navigationState key, where we define our initial route:
You may also want to check out react-native-navigation, a component that aims to provide native navigation on both iOS and Android.
Navigation (Experimental) #
If you are looking for a more powerful navigation API, check out NavigationExperimental. It provides greater customization over your transitions, uses single-directional data flow using reducers to manipulate state at a top-level object, and offloads transition animations to the GPU.
Navigator # | Edit on GitHub |
Navigator handles the transition between different scenes in your app.
-You should consider using this component instead of NavigatorIOS if you're
-building a cross-platform app. Navigator is implemented in JavaScript
-whereas NavigatorIOS is a wrapper around UINavigationController.
To set up the Navigator you provide one or more objects called routes,
+It is implemented in JavaScript and is available on both iOS and Android. If
+you are targeting iOS only, you may also want to consider using
+NavigatorIOS as it leverages native UIKit
+navigation.
To set up the Navigator you provide one or more objects called routes,
to identify each scene. You also provide a renderScene function that
renders the scene for each route object.
In the above example, initialRoute is used to specify the first route. It
-contains a name property that identifies the route. The renderScene
-prop returns a function that displays text based on the route's name.
Additional Scenes #
The first example demonstrated one scene. To set up multiple scenes, you pass
+contains a title property that identifies the route. The renderScene
+prop returns a function that displays text based on the route's title.
Additional Scenes #
The first example demonstrated one scene. To set up multiple scenes, you pass
the initialRouteStack prop to Navigator:
initialRouteStack prop to Navigator:This sets up a left navigator bar button that's visible on scenes after the -the first one. When the button is tapped the navigator is popped.
Scene Transitions #
To change the animation or gesture properties of the scene, provide a +the first one. When the button is tapped the navigator is popped.
Another type of navigation bar, with breadcrumbs, is provided by
+Navigator.BreadcrumbNavigationBar. You can also provide your own navigation
+bar by passing it through the navigationBar prop. See the
+UIExplorer
+demo to try out both built-in navigation bars out and see how to use them.
Scene Transitions #
To change the animation or gesture properties of the scene, provide a
configureScene prop to get the config object for a given route:
NavigatorIOS # | Edit on GitHub |
NavigatorIOS is a wrapper around UIKit navigation, enabling you to
-implement back-swipe functionality in your iOS app. Take a look at
+
NavigatorIOS # | Edit on GitHub |
NavigatorIOS is a wrapper around
+UINavigationController,
+enabling you to implement a navigation stack. It works exactly the same as it
+would on a native app using UINavigationController, providing the same
+animations and behavior from UIKIt.
As the name implies, it is only available on iOS. Take a look at
Navigator for a similar solution for your
-cross-platform needs.
To set up the navigator, provide the initialRoute prop with a route
+cross-platform needs, or check out
+react-native-navigation, a
+component that aims to provide native navigation on both iOS and Android.
To set up the navigator, provide the initialRoute prop with a route
object. A route object is used to describe each scene that your app
navigates to. initialRoute represents the first route in your navigator.
In this code, the navigator sets its title and renders MyView. The
-component specified in initialRoute will receive a route prop and a
-navigator prop representing the navigator.
You can optionally pass in a passProps property to your initialRoute.
+
+ constructor(props, context) {
+ super(props, context);
+ this._onForward = this._onForward.bind(this);
+ this._onBack = this._onBack.bind(this);
+ }
+
+ _onForward() {
+ this.props.navigator.push({
+ title: 'Scene ' + nextIndex,
+ });
+ }
+
+ render() {
+ return (
+ <View>
+ <Text>Current Scene: { this.props.title }</Text>
+ <TouchableHighlight onPress={this._onForward}>
+ <Text>Tap me to load the next scene</Text>
+ </TouchableHighlight>
+ </View>
+ )
+ }
+}
In this code, the navigator renders the component specified in initialRoute,
+which in this case is MyScene. This component will receive a route prop
+and a navigator prop representing the navigator. The navigator's navigation
+bar will render the title for the current scene, "My Initial Scene".
You can optionally pass in a passProps property to your initialRoute.
NavigatorIOS passes this in as props to the rendered component:
You can then access the props passed in:
Handling Navigation #
To trigger navigation functionality such as pushing or popping a view, you +}}
You can then access the props passed in via {this.props.myProp}.
Handling Navigation #
To trigger navigation functionality such as pushing or popping a view, you
have access to a navigator object. The object is passed in as a prop to any
component that is rendered by NavigatorIOS. You can then call the
relevant methods to perform the navigation action you need:
Notice that {pic} is surrounded by braces, to embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.
Your own components can also use props. This lets you make a single component
+AppRegistry.registerComponent('Bananas', () => Bananas);
Notice that {pic} is surrounded by braces, to embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.
Your own components can also use props. This lets you make a single component
that is used in many different places in your app, with slightly different
properties in each place. Just refer to this.props in your render function. Here's an example: