Navigation prop reference
Each screen
component in your app is provided with the navigation
prop automatically. The prop contains various convenience functions that dispatch navigation actions on the route's router. It looks like this:
navigation
navigate
- go to another screen, figures out the action it needs to take to do itreset
- wipe the navigator state and replace it with the result of several actionsgoBack
- close active screen and move back in the stackaddListener
- subscribe to updates to navigation lifecyclesetParams
- make changes to route's paramsdispatch
- send an action to routerdangerouslyGetParent
- function that returns the parent navigator, if any
It's important to highlight the navigation
prop is not passed in to all components; only screen
components receive this prop automatically! React Navigation doesn't do any magic here. For example, if you were to define a MyBackButton
component and render it as a child of a screen component, you would not be able to access the navigation
prop on it. If, however, you wish to access the navigation
prop in any of your components, you may use the useNavigation
hook.
Navigator-dependent functions
There are several additional functions present on navigation
prop based on the kind of the current navigator.
If the navigator is a stack navigator, several alternatives to navigate
and goBack
are provided and you can use whichever you prefer. The functions are:
navigation
replace
- replace the current route with a new onepush
- push a new route onto the stackpop
- go back in the stackpopToTop
- go to the top of the stack
If the navigator is a tab navigator, the following are also available:
navigation
jumpTo
- go to a specific screen in the tab navigator
If the navigator is a drawer navigator, the following are also available:
navigation
jumpTo
- go to a specific screen in the drawer navigatoropenDrawer
- open the drawercloseDrawer
- close the drawertoggleDrawer
- toggle the state, ie. switch from closed to open and vice versa
You can find more details about navigator dependent functions in the documentation for the navigator that you're using.
Common API reference
The vast majority of your interactions with the navigation
prop will involve navigate
, goBack
, and setParams
.
navigate
- Link to other screens
Call this to link to another screen in your app. Takes the following arguments:
navigation.navigate(name, params)
name
- A destination name of the route that has been defined somewhereparams
- Params to merge into the destination route
function HomeScreen({ navigation: { navigate } }) {
return (
<View>
<Text>This is the home screen of the app</Text>
<Button
onPress={() =>
navigate('Profile', { names: ['Brent', 'Satya', 'Michaś'] })
}
title="Go to Brent's profile"
/>
</View>
);
}
goBack
- Close the active screen and move back
Optionally provide a key, which specifies the route to go back from. By default, goBack
will close the route that it is called from:
function ProfileScreen({ navigation: { goBack } }) {
return (
<View>
<Button onPress={() => goBack()} title="Go back from ProfileScreen" />
</View>
);
}
goBack
Going back from a specific screen with Consider the following navigation stack history:
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_A });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_B });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_C });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_D });
Now you are on screen D and want to go back to screen A (popping D, C, and B).
Then you can use navigate
:
navigation.navigate({ key: SCREEN_KEY_A }); // will go to screen A FROM screen D
Alternatively, as screen A is the top of the stack, you can use navigation.popToTop()
.
reset
Replace the navigator state to a new state:
navigation.reset({
index: 0,
routes: [{ name: 'Profile' }],
});
Note: Consider the navigator's state object to be internal and subject to change in a minor release. Avoid using properties from the navigation state object except
index
androutes
, unless you really need it. If there is some functionality you cannot achieve without relying on the structure of the state object, please open an issue.
setParams
- Make changes to route params
Firing the setParams
action allows a screen to change the params in the route, which is useful for updating the header buttons and title. setParams
works like React's setState
- it merges the provided params object with the current params.
function ProfileScreen({ navigation: { setParams } }) {
render() {
return (
<Button
onPress={() =>
navigation.setParams({
friends:
route.params.friends[0] === 'Brent'
? ['Wojciech', 'Szymon', 'Jakub']
: ['Brent', 'Satya', 'Michaś'],
title:
route.params.title === "Brent's Profile"
? "Lucy's Profile"
: "Brent's Profile",
})
}
title="Swap title and friends"
/>
);
}
}
setOptions
- Update screen options from the component
The setOptions
method lets us set screen options from within the component. This is useful if we need to use the component's props, state or context to configure our screen.
function ProfileScreen({ navigation, route }) {
const [value, onChangeText] = React.useState(route.params.title);
navigation.setOptions({
title: value === '' ? 'No title' : value,
});
return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<TextInput
style={{ height: 40, borderColor: 'gray', borderWidth: 1 }}
onChangeText={text => onChangeText(text)}
value={value}
/>
<Button title="Go back" onPress={() => navigation.goBack()} />
</View>
);
}
Any options specified here are shallow merged with the options specified when defining the screen.
Navigation events
Screens can add listeners on the navigation
prop like in React Navigation. By default, there are 2 events available:
focus
- This event is emitted when the screen comes into focusblur
- This event is emitted when the screen goes out of focusstate
(advanced) - This event is emitted when the navigator's state changes
Example:
function Profile({ navigation }) {
React.useEffect(() => {
const unsubscribe = navigation.addListener('focus', () => {
// do something
});
return unsubscribe;
}, [navigation]);
return <ProfileContent />;
}
The navigation.addListener
method returns a function to remove the listener which can be returned as the cleanup function in an effect.
Each event listener receives an event object as it's argument. The event object contains following properties:
data
- Additional data regarding the event passed by the navigator. This can beundefined
if no data was passed.preventDefault
- For some events, there may be apreventDefault
method on the event object. Calling this method will prevent the default action performed by the event (such as switching tabs ontabPress
). Support for preventing actions are only available for certain events liketabPress
and won't work for all events.
Apart from focus
, blur
and state
, each navigator can emit their own custom events. For example, stack navigator emits transitionStart
and transitionEnd
events, tab navigator emits tabPress
event etc. You can find details about the events emitted on the individual navigator's documentation.
You can only listen to events from the immediate parent navigator. For example, if you try to add a listener in a screen is inside a stack that's nested in a tab, it won't get the tabPress
event. If you need to listen to an event from a parent navigator, you may use navigation.dangerouslyGetParent()
to get a reference to parent navigator's navigation prop and add a listener.
isFocused
- Query the focused state of the screen
Returns true
if the screen is focused and false
otherwise.
const isFocused = navigation.isFocused();
This method doesn't re-render the screen when the value changes and mainly useful in callbacks. You probably want to use useIsFocused instead of using this directly, it will return a boolean a prop to indicating if the screen is focused.
Advanced API Reference
The dispatch
function is much less commonly used, but a good escape hatch if you can't do what you need with the available methods such as navigate
, goBack
etc. We recommend to avoid using the dispatch
method often unless absolutely necessary.
dispatch
- Send an action to the router
Use dispatch to send any navigation action to the router. The other navigation functions use dispatch behind the scenes.
Note that if you want to dispatch react-navigation actions you should use the action creators provided in this library.
See Navigation Actions Docs for a full list of available actions.
import { CommonActions } from '@react-navigation/native';
navigation.dispatch(
CommonActions.navigate({
name: 'Profile',
params: {},
})
);
When dispatching action objects, you can also specify few additional properties:
source
- The key of the route which should be considered as the source of the action. The key maybe used by the router to handle the action. For example, thereplace
action will replace the route with the given key. By default, it'll use the key of the route that dispatched the action. You can explicitly passundefined
to override this behavior.target
- The key of the navigation state the action should be applied on. By default, actions bubble to other navigators if not handled by a navigator. Iftarget
is specified, the action won't bubble if the navigator with the same key didn't handle it.
Example:
import { CommonActions } from '@react-navigation/native';
navigation.dispatch({
...CommonActions.navigate('Profile'),
source: 'someRoutekey',
target: 'someStatekey',
});
dangerouslyGetParent
- get parent navigator's navigation prop
This method returns the navigation prop from the parent navigator that the current navigator is nested in. For example, if you have a stack navigator and a tab navigator nested inside the stack, then you can use dangerouslyGetParent
inside a screen of the tab navigator to get the navigation prop passed from the stack navigator.
This method will return undefined
if there is no parent navigator. Be sure to always check for undefined
when using this method.
dangerouslyGetState
- get state of navigator
Note: Consider the navigator's state object to be internal and subject to change in a minor release. Avoid using properties from the navigation state object except
index
androutes
, unless you really need it. If there is some functionality you cannot achieve without relying on the structure of the state object, please open an issue.
This method returns the state object of the navigator which contains the screen. Getting the navigator state could be useful in very rare situations. You most likely don't need to use this method. If you do, make sure you have a good reason.
If you need the state for rendering content, you should use useNavigationState
instead of this method.