Skip to main content

Navigation object reference

The navigation object contains various convenience functions that dispatch navigation actions. It looks like this:

  • navigation
    • navigate - go to the given screen, this will behave differently based on the navigator
    • goBack - go back to the previous screen, this will pop the current screen when used in a stack
    • reset - replace the navigation state of the navigator with the given state
    • preload - preload a screen in the background before navigating to it
    • setParams - merge new params onto the route's params
    • dispatch - send an action object to update the navigation state
    • setOptions - update the screen's options
    • isFocused - check whether the screen is focused
    • canGoBack - check whether it's possible to go back from the current screen
    • getState - get the navigation state of the navigator
    • getParent - get the navigation object of the parent screen, if any
    • addListener - subscribe to events for the screen
    • removeListener - unsubscribe from events for the screen

The navigation object can be accessed inside any screen component with the useNavigation hook.

Screen components defined with the dynamic API also receive the navigation object as a prop. Consider it legacy and prefer using the useNavigation hook instead.

warning

setParams/setOptions etc. should only be called in event listeners or useEffect/useLayoutEffect/componentDidMount/componentDidUpdate etc. Not during render or in constructor.

There are several additional functions present on navigation object 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 screen with a new one
    • push - push a new screen onto the stack
    • pop - go back in the stack
    • popTo - go back to a specific screen in the stack
    • popToTop - go to the top of the stack

See Stack navigator helpers and Native Stack navigator helpers for more details on these methods.

If the navigator is a tab navigator, the following are also available:

  • navigation
    • jumpTo - go to a specific screen in the tab navigator

See Bottom Tab navigator helpers and Material Top Tab navigator helpers for more details on these methods.

If the navigator is a drawer navigator, the following are also available:

  • navigation
    • jumpTo - go to a specific screen in the drawer navigator
    • openDrawer - open the drawer
    • closeDrawer - close the drawer
    • toggleDrawer - toggle the state, ie. switch from closed to open and vice versa

See Drawer navigator helpers for more details on these methods.

Common API reference​

The vast majority of your interactions with the navigation object will involve navigate, goBack, and setParams.

The navigate method lets us navigate to another screen in your app. It takes the following arguments:

navigation.navigate(name, params)

  • name - string - A destination name of the screen in the current or a parent navigator.
  • params - object - Params to use for the destination route.
  • options - Options object containing the following properties:
    • merge - boolean - Whether params should be merged with the existing route params, or replace them (when navigating to an existing screen). Defaults to false.
    • pop - boolean - Whether screens should be popped to navigate to a matching screen in the stack. Defaults to false.
function HomeScreen() {
  const navigation = useNavigation();

  return (
    <View
      style={{
        flex: 1,
        gap: 8,
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <Text>This is the home screen of the app</Text>
      <Button
        onPress={() => {
          navigation.navigate('Profile', {
            names: ['Brent', 'Satya', 'Michaś'],
          });
        }}
      >
        Go to Brent's profile
      </Button>
    </View>
  );
}
Try on Snack

In a stack navigator (stack or native stack), calling navigate with a screen name will have the following behavior:

  • If you're already on a screen with the same name, it will update its params and not push a new screen.
  • If you're on a different screen, it will push the new screen onto the stack.
  • If the getId prop is specified, and another screen in the stack has the same ID, it will bring that screen to focus and update its params instead.
  • If none of the above conditions match, it'll push a new screen to the stack.

In a tab or drawer navigator, calling navigate will switch to the relevant screen if it's not focused already and update the params of the screen.

warning

This method is deprecated and will be removed in a future release. It only exists for compatibility purposes. Use navigate instead.

The navigateDeprecated action implements the old behavior of navigate from previous versions.

It takes the following arguments:

navigation.navigateDeprecated(name, params)

  • name - string - A destination name of the screen in the current or a parent navigator.
  • params - object - Params to use for the destination route.

In a stack navigator (stack or native stack), calling navigate with a screen name will have the following behavior:

  • If you're already on a screen with the same name, it will update its params and not push a new screen.
  • If you're on a different screen, it will push the new screen onto the stack.
  • If the getId prop is specified, and another screen in the stack has the same ID, it will bring that screen to focus and update its params instead.

In a tab or drawer navigator, calling navigate will switch to the relevant screen if it's not focused already and update the params of the screen.

goBack​

The goBack method lets us go back to the previous screen in the navigator.

By default, goBack will go back from the screen that it is called from:

function ProfileScreen({ route }) {
  const navigation = useNavigation();

  return (
    <View
      style={{
        flex: 1,
        gap: 8,
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <Text>Profile Screen</Text>
      <Text>Friends: </Text>
      <Text>{route.params.names[0]}</Text>
      <Text>{route.params.names[1]}</Text>
      <Text>{route.params.names[2]}</Text>
      <Button onPress