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' }));

By default, the action replaces the route that dispatched it. If you want to replace a particular route, you can add a source property referring to the route key:

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

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

push​

The push action adds a route on top of the stack and navigates forward to it.

  • 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' }));

Unlike navigate, which reuses the current screen if it's the same as the destination, push always adds a new instance of the screen on top of the stack.

pop​

The pop action removes history entries from the stack. It takes one optional argument (count), which allows you to specify how many history entries 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));

By default, the action pops history entries from the route that dispatched it. If you want to pop a particular route, you can add a source property referring to the route key:

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

navigation.dispatch({
  ...StackActions.pop(),
  source: route.key,
});

Here, "history entries" refer to 2 things:

If pop is dispatched from a screen earlier in the stack than the focused screen, it'll also remove all the screens above it in the stack, including the focused screen.

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.

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' }));

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.

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());

dismiss​

The dismiss action dismisses the current screen from the stack. It takes one optional argument (count), which allows you to specify how many screens to dismiss.

navigation.dismiss(1);

It can also be used with navigation.dispatch:

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

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

Unlike the pop action, it dismisses the entire screen regardless of param history, and it does not remove screens after the screen being dismissed.

By default, the action dismisses the route that dispatched it. If you want to dismiss a particular route, you can add a source property referring to the route key:

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

navigation.dispatch({
  ...StackActions.dismiss(),
  source: route.key,
});

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, dismiss, 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:

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

navigation.dispatch({
  ...StackActions.retain(true),
  source: route.key,
});