Skip to content

Migrate 'Groups' examples to static API in v7 #1319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 26, 2024
Merged

Migrate 'Groups' examples to static API in v7 #1319

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 203 additions & 14 deletions versioned_docs/version-7.x/group.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,156 @@ title: Group
sidebar_label: Group
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

`Group` components are used to group several [screens](screen.md) inside a navigator.

A `Group` is returned from a `createXNavigator` function:

<Tabs groupId="config" queryString="config">
<TabItem value="static" label="Static" default>

```js
const Stack = createStackNavigator({
screens: {
/* content */
},
groups: {
/* content */
},
}); // Stack contains Screen & Navigator properties
```

</TabItem>
<TabItem value="dynamic" label="Dynamic" default>

```js
const Stack = createStackNavigator(); // Stack contains Screen & Navigator properties
```

</TabItem>
</Tabs>

After creating the navigator, it can be used as children of the `Navigator` component:

<samp id="api-group"/>
<Tabs groupId="config" queryString="config">
<TabItem value="static" label="Static" default>

```js
<Stack.Navigator>
<Stack.Group
screenOptions={{ headerStyle: { backgroundColor: 'papayawhip' } }}
>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Group>
<Stack.Group screenOptions={{ presentation: 'modal' }}>
<Stack.Screen name="Search" component={SearchScreen} />
<Stack.Screen name="Share" component={ShareScreen} />
</Stack.Group>
</Stack.Navigator>
```js name="Stack groups" snack version=7 dependencies=@react-navigation/elements
import * as React from 'react';
import { View, Text } from 'react-native';
import { Button } from '@react-navigation/elements';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import {
createStaticNavigation,
useNavigation,
} from '@react-navigation/native';

function HomeScreen() {
const navigation = useNavigation();

return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
<Button onPress={() => navigation.navigate('Search')}>
Go to Search
</Button>
</View>
);
}

function EmptyScreen() {
return <View />;
}

// codeblock-focus-start
const Stack = createNativeStackNavigator({
screens: {},
groups: {
App: {
screenOptions: {
headerStyle: {
backgroundColor: '#FFB6C1',
},
},
screens: {
Home: HomeScreen,
Profile: EmptyScreen,
},
},
Modal: {
screenOptions: {
presentation: 'modal',
},
screens: {
Search: EmptyScreen,
Share: EmptyScreen,
},
},
},
});
// codeblock-focus-end

const Navigation = createStaticNavigation(Stack);

export default function App() {
return <Navigation />;
}
```

</TabItem>
<TabItem value="dynamic" label="Dynamic" default>

```js name="Stack groups" snack version=7 dependencies=@react-navigation/elements
import * as React from 'react';
import { View, Text } from 'react-native';
import { Button } from '@react-navigation/elements';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { NavigationContainer } from '@react-navigation/native';

const Stack = createNativeStackNavigator();

function HomeScreen({ navigation }) {
return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
<Button onPress={() => navigation.navigate('Search')}>
Go to Search
</Button>
</View>
);
}

function EmptyScreen() {
return <View />;
}

export default function App() {
return (
<NavigationContainer>
// codeblock-focus-start
<Stack.Navigator>
<Stack.Group
screenOptions={{ headerStyle: { backgroundColor: 'papayawhip' } }}
>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Profile" component={EmptyScreen} />
</Stack.Group>
<Stack.Group screenOptions={{ presentation: 'modal' }}>
<Stack.Screen name="Search" component={EmptyScreen} />
<Stack.Screen name="Share" component={EmptyScreen} />
</Stack.Group>
</Stack.Navigator>
// codeblock-focus-end
</NavigationContainer>
);
}
```

</TabItem>
</Tabs>

It's also possible to nest `Group` components inside other `Group` components.

## Props
Expand All @@ -39,6 +162,26 @@ It's also possible to nest `Group` components inside other `Group` components.

Options to configure how the screens inside the group get presented in the navigator. It accepts either an object or a function returning an object:

<Tabs groupId="config" queryString="config">
<TabItem value="static" label="Static" default>

```js
const Stack = createNativeStackNavigator({
screens: {},
groups: {
screenOptions: {
presentation: 'modal',
},
screens: {
/* screens */
},
},
});
```

</TabItem>
<TabItem value="dynamic" label="Dynamic" default>

```js
<Stack.Group
screenOptions={{
Expand All @@ -49,8 +192,31 @@ Options to configure how the screens inside the group get presented in the navig
</Stack.Group>
```

</TabItem>
</Tabs>

When you pass a function, it'll receive the [`route`](route-object.md) and [`navigation`](navigation-object.md):

<Tabs groupId="config" queryString="config">
<TabItem value="static" label="Static" default>

```js
const Stack = createNativeStackNavigator({
screens: {},
groups: {
screenOptions: ({ route, navigation }) => ({
title: route.params.title,
}),
screens: {
/* screens */
},
},
});
```

</TabItem>
<TabItem value="dynamic" label="Dynamic" default>

```js
<Stack.Group
screenOptions={({ route, navigation }) => ({
Expand All @@ -61,18 +227,41 @@ When you pass a function, it'll receive the [`route`](route-object.md) and [`nav
</Stack.Group>
```

</TabItem>
</Tabs>

These options are merged with the `options` specified in the individual screens, and the screen's options will take precedence over the group's options.

See [Options for screens](screen-options.md) for more details and examples.

### `navigationKey`

Optional key for a group of screens screen. If the key changes, all existing screens in this group will be removed (if used in a stack navigator) or reset (if used in a tab or drawer navigator):
<Tabs groupId="config" queryString="config">
<TabItem value="static" label="Static" default>

```js
const Stack = createNativeStackNavigator({
screens: {},
groups: {
navigationKey: isSignedIn ? 'user' : 'guest',
screens: {
/* screens */
},
},
});
```

</TabItem>
<TabItem value="dynamic" label="Dynamic" default>

```js
<Stack.Group navigationKey={isSignedIn ? 'user' : 'guest'}>
{/* screens */}
</Stack.Group>
```

</TabItem>
</Tabs>

This is similar to the [`navigationKey`](screen.md#navigationkey) prop on `Screen`, but applies to a group of screens.