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.

For screens inside a Stack Navigator or Native Stack Navigator, all stack actions are available as methods on the navigation object.

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.replace('Profile', { user: 'Wojtek' });

It can also be used with navigation.dispatch:

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

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.push('Profile', { user: 'Wojtek' });

It can also be used with navigation.dispatch:

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

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.pop(1);

It can also be used with navigation.dispatch:

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

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.popTo('Profile', { user: 'jane' });

It can also be used with navigation.dispatch:

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

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.

navigation.popToTop();

It can also be used with navigation.dispatch:

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

navigation.dispatch(StackActions.popToTop());

retain​

The retain action marks a route to be retained in the navigation state after it is removed from history.

It takes the following argument:

  • enable - boolean - Whether to retain the route. Passing true marks the route to be retained, while false unmarks it.
navigation.retain(true);

It can also be used with navigation.dispatch:

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

navigation.dispatch(StackActions.retain(true));

When a screen is marked to be retained, actions such as goBack, pop, popToTop, replace etc. will remove it from history, but keep it in the navigation state. So the screen is not unmounted and stays rendered in the background, preserving its local state. Similar to preloaded routes, it can be brought to focus with navigate.

This can be useful in various scenarios:

  • Keeping a frequently used heavy screen in memory to avoid unmounting and remounting it for better performance when navigating back and forth.
  • Keeping a screen with a video or audio player rendered to enable functionality such as background playback or picture-in-picture mode when the user navigates away from the screen.

If a route was removed from history while being retained, retain(false) will remove it from the navigation state and unmount the screen. If the route is still present in history, retain(false) will just unmark it, and the route will be removed from the navigation state when it's removed from history.

By default, the action applies to the route that dispatched it. If you want to retain 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.retain(true),
  source: route.key,
  target: navigation.getState().key,
});