Custom navigators
A navigator is any React component that has a router on it, to define the navigation behavior. Each navigator is given a navigation
prop, which allows the parent to control the navigation state.
#
Extending NavigatorsIt is possible to take an existing Navigator and extend its behavior, using the following approach:
Now it is possible to render additional things, observe the navigation prop, and override behavior of the router:
#
Navigator Navigation PropThe navigation prop passed down to a navigator only includes state
, dispatch
, and addListener
. This is the current state of the navigator, and an event channel to send action requests.
All navigators are controlled components: they always display what is coming in through props.navigation.state
, and their only way to change the state is to send actions into props.navigation.dispatch
.
Navigators can specify custom behavior to parent navigators by customizing their router. For example, a navigator is able to specify when actions should be blocked by returning null from router.getStateForAction
. Or a navigator can specify custom URI handling by overriding router.getActionForPathAndParams
to output a relevant navigation action, and handling that action in router.getStateForAction
.
#
Navigation StateThe navigation state that is passed into a navigator's props.navigation.state
has the following structure:
#
Navigation DispatchersA navigator can dispatch navigation actions, such as 'Go to a URI', 'Go back'.
The dispatcher will return true
if the action was successfully handled, otherwise false
.
#
API for building custom navigatorsTo help developers implement custom navigators, the following utilities are provided with React Navigation:
createNavigator
#
Note: The
createNavigator
API has changed in version 2. The old doc for v1 can be accessed here: https://v1.reactnavigation.org/docs/custom-navigators.html
This utility combines a router and a navigation view together in a standard way:
The new AppNavigator
can be rendered as such:
Then the view will be rendered in the following way:
The navigation
prop is the same navigation prop that was passed into the navigator.
Both navigationConfig
and screenProps
are simply passed through, as defined above.
Most information about child screens comes through the descriptors
prop. The descriptors is an object map of route keys to scene descriptors. There is one descriptor for each child route.
#
Scene DescriptorsA scene descriptor has the following properties:
getComponent
, a function that returns the component for the screenoptions
, the flattened navigationOptions for the routenavigation
, the child navigation prop, including actions and the routestate
state
, the navigation state for the child screen (a shortcut fornavigation.state
)key
, the key of the route (a shortcut fornavigation.state.key
)
createNavigationContainer
#
If you want your navigator to be usable as a top-level component, (without a navigation prop being passed in), you can use createNavigationContainer
. This utility will make your navigator act like a top-level navigator when the navigation prop is missing. It will manage the app state, and integrate with app-level nav features, like handling incoming and outgoing links, and Android back button behavior.