diff --git a/versioned_docs/version-7.x/navigation-actions.md b/versioned_docs/version-7.x/navigation-actions.md
index 2e60168b3f6..bafc95142f7 100755
--- a/versioned_docs/version-7.x/navigation-actions.md
+++ b/versioned_docs/version-7.x/navigation-actions.md
@@ -4,6 +4,9 @@ title: CommonActions reference
sidebar_label: CommonActions
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
A navigation action is an object containing at least a `type` property. Internally, the action can be handled by [routers](custom-routers.md) with the `getStateForAction` method to return a new state from an existing [navigation state](navigation-state.md).
Each navigation actions can contain at least the following properties:
@@ -26,21 +29,240 @@ The `navigate` action allows to navigate to a specific route. It takes the follo
- `name` - _string_ - A destination name of the screen in the current or a parent navigator.
- `params` - _object_ - Params to use for the destination route.
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions navigate" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
+});
+
+const Navigation = createStaticNavigation(Stack);
+
+export default function App() {
+ return ;
+}
+```
+
+
+
-navigation.dispatch(
- CommonActions.navigate({
- name: 'Profile',
- params: {
- user: 'jane',
- },
- })
-);
+```js name="Common actions navigate" snack version=7
+import * as React from 'react';
+import { Button } from '@react-navigation/elements';
+import { View, Text } from 'react-native';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
+
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
```
+
+
+
In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack-navigator.md)), 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.
@@ -60,25 +282,240 @@ The `reset` action allows to reset the [navigation state](navigation-state.md) t
- `state` - _object_ - The new [navigation state](navigation-state.md) object to use.
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions reset" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
+});
-navigation.dispatch(
- CommonActions.reset({
- index: 1,
- routes: [
- { name: 'Home' },
- {
- name: 'Profile',
- params: { user: 'jane' },
- },
- ],
- })
-);
+const Navigation = createStaticNavigation(Stack);
+
+export default function App() {
+ return ;
+}
+```
+
+
+
+
+```js name="Common actions reset" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
+
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
```
+
+
+
The state object specified in `reset` replaces the existing [navigation state](navigation-state.md) with the new one. This means that if you provide new route objects without a key, or route objects with a different key, it'll remove the existing screens for those routes and add new screens.
If you want to preserve the existing screens but only want to modify the state, you can pass a function to `dispatch` where you can get the existing state. Then you can change it as you like (make sure not to mutate the existing state, but create new state object for your changes). and return a `reset` action with the desired state:
@@ -86,9 +523,9 @@ If you want to preserve the existing screens but only want to modify the state,
```js
import { CommonActions } from '@react-navigation/native';
-navigation.dispatch(state => {
+navigation.dispatch((state) => {
// Remove all the screens after `Profile`
- const index = state.routes.findIndex(r => r.name === 'Profile');
+ const index = state.routes.findIndex((r) => r.name === 'Profile');
const routes = state.routes.slice(0, index + 1);
return CommonActions.reset({
@@ -118,28 +555,484 @@ So if you have such a use case, consider a different approach - e.g. updating th
The `goBack` action creator allows to go back to the previous route in history. It doesn't take any arguments.
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions goBack" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
+});
+
+const Navigation = createStaticNavigation(Stack);
+
+export default function App() {
+ return ;
+}
+```
+
+
+
+
+```js name="Common actions goBack" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
-navigation.dispatch(CommonActions.goBack());
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
```
+
+
+
If you want to go back from a particular route, you can add a `source` property referring to the route key and a `target` property referring to the `key` of the navigator which contains the route:
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions goBack" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
-navigation.dispatch({
- ...CommonActions.goBack(),
- source: route.key,
- target: state.key,
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
});
+
+const Navigation = createStaticNavigation(Stack);
+
+export default function App() {
+ return ;
+}
+```
+
+
+
+
+```js name="Common actions goBack" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
+
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
```
+
+
+
By default, the key of the route which dispatched the action is passed as the `source` property and the `target` property is `undefined`.
### setParams
@@ -148,25 +1041,474 @@ The `setParams` action allows to update params for a certain route. It takes the
- `params` - _object_ - required - New params to be merged into existing route params.
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions setParams" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
+});
+
+const Navigation = createStaticNavigation(Stack);
-navigation.dispatch(CommonActions.setParams({ user: 'Wojtek' }));
+export default function App() {
+ return ;
+}
```
+
+
+
+```js name="Common actions setParams" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
+
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
+```
+
+
+
+
If you want to set params for a particular route, you can add a `source` property referring to the route key:
-
+
+
-```js
-import { CommonActions } from '@react-navigation/native';
+```js name="Common actions setParams" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ createStaticNavigation,
+ useNavigation,
+ CommonActions,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen() {
+ const navigation = useNavigation();
+
+ return (
+
+ Home!
+
+
+
+ );
+}
-navigation.dispatch({
- ...CommonActions.setParams({ user: 'Wojtek' }),
- source: route.key,
+function ProfileScreen({ route }) {
+ const navigation = useNavigation();
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator({
+ screens: {
+ Home: HomeScreen,
+ Profile: ProfileScreen,
+ },
});
+
+const Navigation = createStaticNavigation(Stack);
+
+export default function App() {
+ return ;
+}
```
+
+
+
+```js name="Common actions setParams" snack version=7
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@react-navigation/elements';
+import {
+ NavigationContainer,
+ CommonActions,
+ useNavigation,
+} from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+
+function HomeScreen({ navigation }) {
+ return (
+
+ Home!
+
+
+
+ );
+}
+
+function ProfileScreen({ navigation, route }) {
+ return (
+
+ Profile!
+ {route.params.user}'s profile
+
+
+
+
+
+ );
+}
+
+const Stack = createStackNavigator();
+
+export default function App() {
+ return (
+
+
+
+
+
+
+ );
+}
+```
+
+
+
+
If the `source` property is explicitly set to `undefined`, it'll set the params for the focused route.