Skip to main content
Version: 7.x

Navigator

A navigator is responsible for managing and rendering a set of screens. It can be created using the createXNavigator functions, e.g. createStackNavigator, createNativeStackNavigator, createBottomTabNavigator, createMaterialTopTabNavigator, createDrawerNavigator etc.:

const MyStack = createNativeStackNavigator({
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});

In addition to the built-in navigators, it's also possible to build your custom navigators or use third-party navigators. See custom navigators for more details.

Configuration

Different navigators accept different configuration options. You can find the list of options for each navigator in their respective documentation.

There is a set of common configurations that are shared across all navigators:

ID

Optional unique ID for the navigator. This can be used with navigation.getParent to refer to this navigator in a child navigator.

const MyStack = createNativeStackNavigator({
id: 'RootStack',
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});

Initial route name

The name of the route to render on the first load of the navigator.

const MyStack = createNativeStackNavigator({
initialRouteName: 'Home',
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});

Layout

A layout is a wrapper around the navigator. It can be useful for augmenting the navigators with additional UI with a wrapper.

The difference from adding a wrapper around the navigator manually is that the code in a layout callback has access to the navigator's state, options etc.:

const MyStack = createNativeStackNavigator({
layout: ({ children, state, descriptors, navigation }) => (
<View style={styles.container}>
<Breadcrumbs
state={state}
descriptors={descriptors}
navigation={navigation}
/>
{children}
</View>
),
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});

Screen options

Default options to use for all the screens in the navigator. It accepts either an object or a function returning an object:

const MyStack = createNativeStackNavigator({
screenOptions: {
headerShown: false,
},
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});

See Options for screens for more details and examples.

Screen listeners

Event listeners can be used to subscribe to various events emitted for the screen. See screenListeners prop on the navigator for more details.

Screen layout

A screen layout is a wrapper around each screen in the navigator. It makes it easier to provide things such as a common error boundary and suspense fallback for all screens in the navigator:

const MyStack = createNativeStackNavigator({
screenLayout: ({ children }) => (
<ErrorBoundary>
<React.Suspense
fallback={
<View style={styles.fallback}>
<Text style={styles.text}>Loading…</Text>
</View>
}
>
{children}
</React.Suspense>
</ErrorBoundary>
),
screens: {
Home: HomeScreen,
Profile: ProfileScreen,
},
});