React Native — Understanding the Navigator Component

Recently, I had the opportunity to start work on a personal project — an iOS app — using React Native. I’ve only developed for one platform in the past — the web — and the steep learning curve associated with that worried me that I was in for more of the same on a new platform.

I’m happy to report that my fears have been unfounded. The official React Native docs, and especially The Basics section of those docs, have been a godsend. They provide clear, concise, and current explanation of core concepts in React Native. Kudos to the React Native team and contributors for a top-rate set of docs!

However, one area that I did find lacking is the explanation of how the Navigator component works. In this post, I will explore the documentation on the Navigator component, what parts I find confusing, and then give what I believe to be a more concise explanation of Navigator.

Note: This post deals strictly with what I found confusing about the documentation, given the associations I make about certain concepts. For example, when I think of a stack, I automatically think about an array. (Yes arrays are not stacks, but the association is natural to me). I don’t think that my associations are particularly novel, which is why I believe this post will apply to many others reading the React Native docs for the first time as well.

The Basics — Using Navigators

If you follow the official React Native documentation in a linear fashion, Using Navigators will be your introduction to the Navigator component.

The Index Property on a Route

In that documentation, the first code example that we are given of using a Navigator component is the following:

This is an unfortunate example. Earlier in the documentation, we’ve been introduced to the idea of thinking of a Navigator as a stack of scenes. When I hear stack in the context of JavaScript, I automatically think of implementing a stack with an array as a data structure. Combine that with the fact that the example route has in index property, and I start to wonder what the purpose of the index property is, since an index and an array an intimately tied together. Does the index property determine where in the stack to place this particular route? That would be inconsistent with the expected behavior of a stack — maybe stack was the wrong word to describe Navigator.

(The confusion is made even more acute by the Components — Navigator documentation, which reads: “Each route has an index property that is used to manage the scene being rendered.”)

The Explanation of a Route

In the official documentation, a route is explained as follows:

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. It can have any number of keys to help distinguish your scene, and I happened to pick a single title key for the above example.

To an experienced React / React Native / JavaScript developer, this explanation may not be a problem. To a beginner, however, there is not only a lot to tease out here, but there is also a lot of information that is left out or that has to be inferred.

Personally, I would replace it with the following definition:

A route is a plain old JavaScript object. Whenever we invoked the function in the Navigator’s renderScene prop, the route will be passed as the first argument. The function can then used the route to determine 1) what scene / component to render, and 2) what props and prop values to pass to that scene.

Explanation of renderScene is Lacking

Another area that led to confusion is that there is never any mention that the function in the Navigator’s renderScene prop is invoked whenever navigator.push or navigator.pop is invoked. This has to be inferred only after struggling with what is actually going on.

A corollary to this is that each scene must be have access to the navigator object so that it can call navigator.pop / navigator.push and transition to a new scene. (This particular issue is being addressed Pull Request #9355).

A Route Must Identify What Component to Render

One of the items that I found most confusing about the examples in the docs is that they were not clear on how the Navigator decides which scene to render next. The reason for this is that the examples do not actually transition from one scene to another — they simply transition between the same scene with different props. As a result, the Navigator only has one scene to render, which means it doesn’t have to decide — there is only one possibility on what to render.

While I am sympathetic to the need to keep thing simple in an example, I think that this particular issue could have been addressed with a simple update to one of the first code examples:


In summary, the React Native docs are exemplary — except, in my opinion, when it comes to the Navigation component. The use of index as a property of a route is easily mixed up with the idea of a stack; the explanation of a route is not as straight-forward as it can be; there is no explanation as to when renderScene is invoked; and there are no examples that explain that the renderScene function must be able to determine what scene to render from the information in the route.

P.S. I wrote this post in part to get feedback from others if the docs are confusing to them, and, if so, spend some time making a pull request.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.