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:
(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.
Personally, I would replace it with the following definition:
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.