Navigators allow you to define your application's navigation structure. Navigators also render common elements such as headers and tab bars which you can configure.
Under the hood, navigators are plain React components.
We include some commonly needed navigators such as:
createStackNavigator- Renders one screen at a time and provides transitions between screens. When a new screen is opened it is placed on top of the stack.
createDrawerNavigator- Provides a drawer that slides in from the left of the screen by default.
createBottomTabNavigator- Renders a tab bar that lets the user switch between several screens.
createMaterialTopTabNavigator- Renders tab view which lets the user switch between several screens using swipe gesture or the tab bar.
createMaterialBottomTabNavigator- Renders tab view which lets the user switch between several screens using swipe gesture or the tab bar.
API for building custom navigators
A navigator bundles a router and a view which takes the navigation state and decides how to render it. We export a
useNavigationBuilder hook to build custom navigators that integrate with rest of React Navigation.
This hook allows a component to hook into React Navigation. It accepts the following arguments:
createRouter- A factory method which returns a router object (e.g.
options- Options for the hook and the router. The navigator should forward its props here so that user can provide props to configure the navigator. By default, the following options are accepted:
children(required) - The
childrenprop should contain route configurations as
screenOptionsprop should contain default options for all of the screens.
initialRouteNameprop determines the screen to focus on initial render. This prop is forwarded to the router.
If any other options are passed here, they'll be forwarded to the router.
The hook returns an object with following properties:
state- The navigation state for the navigator. The component can take this state and decide how to render it.
navigation- The navigation object containing various helper methods for the navigator to manipulate the navigation state. This isn't the same as the navigation object for the screen and includes some helpers such as
emitto emit events to the screens.
descriptors- This is an object containing descriptors for each route with the route keys as its properties. The descriptor for a route can be accessed by
descriptors[route.key]. Each descriptor contains the following properties:
navigation- The navigation prop for the screen. You don't need to pass this to the screen manually. But it's useful if we're rendering components outside the screen that need to receive
navigationprop as well, such as a header component.
options- A getter which returns the options such as
titlefor the screen if they are specified.
render- A function which can be used to render the actual screen. Calling
descriptors[route.key].render()will return a React element containing the screen content. It's important to use this method to render a screen, otherwise any child navigators won't be connected to the navigation tree properly.
navigation object for navigators also has an
emit method to emit custom events to the child screens. The usage looks like this:
data is available under the
data property in the
event object, i.e.
target property determines the screen that will receive the event. If the
target property is omitted, the event is dispatched to all screens in the navigator.
createNavigatorFactory function is used to create a function that will
Screen pair. Custom navigators need to wrap the navigator component in
createNavigatorFactory before exporting.
Then it can be used like this:
To type-check navigators, we need to provide 3 types:
- Type of the props accepted by the view
- Type of supported screen options
- A map of event types emitted by the navigator
For example, to type-check our custom tab navigator, we can do something like this:
All of the built-in navigators export their views, which we can reuse and build additional functionality on top of them. For example, if we want to re-build the bottom tab navigator, we need the following code:
Now, we can customize it to add additional functionality or change the behavior. For example, use a custom router instead of the default