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

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

Try on Snack

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.

Dynamic

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>

Try on Snack

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

const MyStack = createNativeStackNavigator({
  groups: {
    Modal: {
      screenOptions: {
        presentation: 'modal',
      },
      screens: {
        /* screens */
      },
    },
  },
});

Dynamic

<Stack.Group
  screenOptions={{
    presentation: 'modal',
  }}
>
  {/* screens */}
</Stack.Group>

When you pass a function, it'll receive the route and navigation:

Static

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

Dynamic

<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

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 */
      },
    },
  },
});

Dynamic

<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

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.

Dynamic

<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.