Skip to main content
Version: 7.x

Options for screens

Each screen can configure various aspects about how it gets presented in the navigator that renders it by specifying certain options, for example, the header title in stack navigator, tab bar icon in bottom tab navigator etc. Different navigators support different set of options.

In the configuring the header bar section of the fundamentals documentation we explain the basics of how this works. Also see the screen options resolution guide to get an idea of how they work when there are multiple navigators.

There are 3 ways of specifying options for screens:

options prop on Screen​

You can pass a prop named options to the Screen component to configure a screen, where you can specify an object with different options for that screen:

const Stack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        title: 'Awesome app',
      },
    },
    Profile: {
      screen: ProfileScreen,
      options: {
        title: 'My profile',
      },
    },
  },
});

const Navigation = createStaticNavigation(Stack);

export default function App() {
  return <Navigation />;
}
Try on Snack

You can also pass a function to options. The function will receive the navigation object and the route object for that screen, as well as the theme object. This can be useful if you want to perform navigation in your options:

const Stack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: ({ navigation }) => ({
        title: 'Awesome app',
        headerLeft: () => {
          <DrawerButton onPress={() => navigation.toggleDrawer()} />;
        },
      }),
    },
  },
});

screenOptions prop on Group​

You can pass a prop named screenOptions to the Group component to configure screens inside the group, where you can specify an object with different options. The options specified in screenOptions apply to all of the screens in the group.

Example:

const Stack = createNativeStackNavigator({
  groups: {
    App: {
      screenOptions: {
        headerStyle: {
          backgroundColor: '#FFB6C1',
        },
      },
      screens: {
        Home: ScreenWithButton('Home', 'Profile'),
        Profile: ScreenWithButton('Profile', 'Settings'),
      },
    },
    Modal: {
      screenOptions: {
        presentation: 'modal',
      },
      screens: {
        Settings: ScreenWithButton('Settings', 'Share'),
        Share: ScreenWithButton('Share'),
      },
    },
  },
});
Try on Snack

Similar to options, you can also pass a function to screenOptions. The function will receive the navigation object and the route object for each screen. This can be useful if you want to configure options for all the screens in one place based on the route:

const Stack = createNativeStackNavigator({
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
  groups: {
    Modal: {
      screenOptions: {
        presentation: 'modal',
        headerLeft: () => <CancelButton onPress={navigation.goBack} />,
      },
      screens: {
        Settings: Settings,
        Share: Share,
      },
    },
  },
});

screenOptions prop on the navigator​

You can pass a prop named screenOptions to the navigator component, where you can specify an object with different options. The options specified in screenOptions apply to all of the screens in the navigator. So this is a good place to add specify options that you want to configure for the whole navigator.

Example:

const Stack = createNativeStackNavigator({
  screenOptions: {
    headerStyle: {
      backgroundColor: 'papayawhip',
    },
  },
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
});

Similar to options, you can also pass a function to screenOptions. The function will receive the navigation object and the route object for each screen. This can be useful if you want to configure options for all the screens in one place based on the route:

const Tab = createBottomTabNavigator({
  screenOptions: ({ route }) => ({
    tabBarIcon: ({ color, size }) => {
      const icons = {
        Home: 'home',
        Profile: 'account',
      };

      return (
        <MaterialCommunityIcons
          name={icons[route.name]}
          color={color}
          size={size}
        />
      );
    },
  }),
  screens: {
    Home: EmptyScreen,
    Profile: EmptyScreen,
  },
});
Try on Snack

The navigation object has a setOptions method that lets you update the options for a screen from within a component. See navigation object's docs for more details.

<Button
  title="Update options"
  onPress={() => navigation.setOptions({ title: 'Updated!' })}
/>