Skip to main content
Version: 8.x

StackActions reference

StackActions is an object containing methods for generating actions specific to stack-based navigators. Its methods expand upon the actions available in CommonActions.

The following actions are supported:

replace​

The replace action allows to replace a route in the navigation state. It takes the following arguments:

  • name - string - A destination name of the route that has been registered somewhere.
  • params - object - Params to pass to the destination route.
navigation.dispatch(
  StackActions.replace('Profile', { user: 'Wojtek' })
);

If you want to replace a particular route, you can add a source property referring to the route key and target property referring to the navigation state key:

import { StackActions } from '@react-navigation/native';

navigation.dispatch({
  ...StackActions.replace('Profile', {
    user: 'jane',
  }),
  source: route.key,
  target: navigation.getState().key,
});

If the source property is explicitly set to undefined, it'll replace the focused route.

push​

The push action adds a route on top of the stack and navigates forward to it. This differs from navigate in that navigate will pop back to earlier in the stack if a route of the given name is already present there. push will always add on top, so a route can be present multiple times.

  • name - string - Name of the route to push onto the stack.
  • params - object - Screen params to pass to the destination route.
navigation.dispatch(StackActions.push('Profile', { user: 'Wojtek' }));

pop​

The pop action takes you back to a previous screen in the stack. It takes one optional argument (count), which allows you to specify how many screens to pop back by.

navigation.dispatch(StackActions.pop(1));

popTo​

The popTo action takes you back to a previous screen in the stack by the name. It also allows you to pass params to the route.

If a matching screen is not found in the stack, this will pop the current screen and add a new screen with the specified name and params - essentially behaving like a replace. This ensures that the app doesn't break if a previous screen with the name did not exist - which can happen when the screen was opened from a deep link or push notification, or when used on the web etc.

The method accepts the following arguments:

  • name - string - Name of the route to navigate to.
  • params - object - Screen params to pass to 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.

If getId is specified for the screen, popTo will match the screen by id instead of name.

navigation.dispatch(StackActions.popTo('Profile', { user: 'jane' }));

popToTop​

The popToTop action takes you back to the first screen in the stack, dismissing all the others. It's functionally identical to StackActions.pop({n: currentIndex}).

navigation.dispatch(StackActions.popToTop());