Group
A group contains several screens inside a navigator for organizational purposes. They can also be used to apply the same options such as header styles to a group of screens, or to define a common layout etc.
- Static
- Dynamic
Groups can be defined using the groups
property in the navigator configuration:
const MyStack = createNativeStackNavigator({
groups: {
App: {
screenOptions: {
headerStyle: {
backgroundColor: '#FFB6C1',
},
},
screens: {
Home: HomeScreen,
Profile: EmptyScreen,
},
},
Modal: {
screenOptions: {
presentation: 'modal',
},
screens: {
Search: EmptyScreen,
Share: EmptyScreen,
},
},
},
});
The keys of the groups
object (e.g. Guest
, User
) are used as the navigationKey
for the group. You can use any string as the key.
A Group
component is returned from a createXNavigator
function. After creating the navigator, it can be used as children of the Navigator
component:
<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>
It's also possible to nest Group
components inside other Group
components.
Configuration
Screen options
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:
- Static
- Dynamic
const MyStack = createNativeStackNavigator({
groups: {
Modal: {
screenOptions: {
presentation: 'modal',
},
screens: {
/* screens */
},
},
},
});
<Stack.Group
screenOptions={{
presentation: 'modal',
}}
>
{/* screens */}
</Stack.Group>
When you pass a function, it'll receive the route
and navigation
:
- Static
- Dynamic
const MyStack = createNativeStackNavigator({
groups: {
Modal: {
screenOptions: ({ route, navigation }) => ({
title: route.params.title,
}),
screens: {
/* screens */
},
},
},
});
<Stack.Group
screenOptions={({ route, navigation }) => ({
title: route.params.title,
})}
>
{/* screens */}
</Stack.Group>
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 for more details and examples.
Screen layout
A screen layout is a wrapper around each screen in the group. It makes it easier to provide things such as a common error boundary and suspense fallback for all screens in a group:
- Static
- Dynamic
const MyStack = createNativeStackNavigator({
groups: {
Modal: {
screenLayout: ({ children }) => (
<ErrorBoundary>
<React.Suspense
fallback={
<View style={styles.fallback}>
<Text style={styles.text}>Loading…</Text>
</View>
}
>
{children}
</React.Suspense>
</ErrorBoundary>
),
screens: {
/* screens */
},
},
},
});
<Stack.Group
screenLayout={({ children }) => (
<ErrorBoundary>
<React.Suspense
fallback={
<View style={styles.fallback}>
<Text style={styles.text}>Loading…</Text>
</View>
}
>
{children}
</React.Suspense>
</ErrorBoundary>
)}
>
{/* screens */}
</Stack.Group>
Navigation key
Optional key for a group of screens. 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):
- Static
- Dynamic
The name of the group is used as the navigationKey
:
const MyStack = createNativeStackNavigator({
groups: {
User: {
screens: {
/* screens */
},
},
Guest: {
screens: {
/* screens */
},
},
},
});
This means if a screen is defined in 2 groups and the groups use the if
property, the screen will remount if the condition changes resulting in one group being removed and the other group being used.
<Stack.Group
navigationKey={isSignedIn ? 'user' : 'guest'}
>
{/* screens */}
</Stack.Group>
This is similar to the navigationKey
prop for screens, but applies to a group of screens.