Skip to main content
Version: 4.x

createStackNavigator

Provides a way for your app to transition between screens where each new screen is placed on top of a stack.

By default the stack navigator is configured to have the familiar iOS and Android look & feel: new screens slide in from the right on iOS, fade in from the bottom on Android. On iOS the stack navigator can also be configured to a modal style where screens slide in from the bottom.

To use this navigator, ensure that you have react-navigation and its dependencies installed, then install react-navigation-stack.

npm install react-navigation-stack @react-native-community/masked-view

API Definition​

import { createStackNavigator } from 'react-navigation-stack';

createStackNavigator(RouteConfigs, StackNavigatorConfig);

RouteConfigs​

The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route.

createStackNavigator({
  // For each screen that you can navigate to, create a new entry like this:
  Profile: {
    // `ProfileScreen` is a React component that will be the main content of the screen.
    screen: ProfileScreen,
    // When `ProfileScreen` is loaded by the StackNavigator, it will be given a `navigation` prop.

    // Optional: When deep linking or using react-navigation in a web app, this path is used:
    path: 'people/:name',
    // The action and route params are extracted from the path.

    // Optional: Override the `navigationOptions` for the screen
    navigationOptions: ({ navigation }) => ({
      title: `${navigation.state.params.name}'s Profile'`,
    }),
  },

  ...MyOtherRoutes,
});

StackNavigatorConfig​

Options for the router:

  • initialRouteName - Sets the default screen of the stack. Must match one of the keys in route configs.
  • initialRouteParams - The params for the initial route
  • initialRouteKey - Optional identifier of the initial route
  • navigationOptions - Navigation options for the navigator itself, to configure a parent navigator
  • defaultNavigationOptions - Default navigation options to use for screens
  • paths - A mapping of overrides for the paths set in the route configs
  • detachInactiveScreens - Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. Make sure to call enableScreens from react-native-screens to make it work. Defaults to true on Android and false on iOS.

Visual options:

  • mode - Defines the style for rendering and transitions:
    • card - Use the standard iOS and Android screen transitions. This is the default.
    • modal - This does few things:
      • Sets headerMode to screen for the stack unless specified
      • Prevents last inactive screen from being detached so that it stays visible underneath the active screen
      • Make the screens slide in from the bottom on iOS which is a common iOS pattern.
  • headerMode - Specifies how the header should be rendered:
    • float - The header is rendered above the screen and animates independently of the screen. This is default on iOS for non-modals.
    • screen - The header is rendered as part of the screen and animates together with the screen. This is default on other platforms.
    • none - No header will be rendered.
  • keyboardHandlingEnabled - If false, the on screen keyboard will NOT automatically dismiss when navigating to a new screen. Defaults to true.

title​

String that can be used as a fallback for headerTitle. Additionally, will be used as a fallback for tabBarLabel (if nested in a TabNavigator) or drawerLabel (if nested in a DrawerNavigator).

detachPreviousScreen​

Boolean used to indicate whether to detach the previous screen from the view hierarchy to save memory. Set it to false if you need the previous screen to be seen through the active screen. Only applicable if detachInactiveScreens isn't set to false. Defaults to false for the last screen when mode='modal', otherwise true.

Function that given HeaderProps returns a React Element, to display as a header.

Example:

header: ({ scene, previous, navigation }) => {
  const { options } = scene.descriptor;
  const title =
    options.headerTitle !== undefined
      ? options.headerTitle
      : options.title !== undefined
        ? options.title
        : scene.route.routeName;

  return (