Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 71 ยท Navigation

Stack Navigation with React Navigation

Set up a native stack with React Navigation: screens, navigate, push, goBack, replace, popToTop and header options, plus a runnable stack navigator stand-in.

Almost every app has more than one screen. A list leads to a detail page, a detail page leads to an edit form, and the back button brings you home again. The stack navigator is the tool for this: it keeps a pile of screens, shows the one on top, and gives you a header with a back button for free.

React Navigation is the most widely used navigation library for React Native. Its createNativeStackNavigator uses the platform's own screen containers (through react-native-screens), so transitions and the swipe-back gesture feel native. If the idea of a history stack is new to you, read Navigation Concepts for Mobile first.

What runs on this site. React Navigation needs a native runtime, so the real code below is read-only. The runnable examples are stand-ins: a small reducer that behaves like a stack navigator (navigate, push, goBack, replace, popToTop) and a React component that draws the top screen and a header. The stack rules are the real ones, but there are no native transitions or gestures.

Installing and creating a stack

In an Expo project you install the core package, the native stack and the two native peers that every navigator needs:

Terminal
npm install @react-navigation/native @react-navigation/native-stack
npx expo install react-native-screens react-native-safe-area-context

Then wrap your app in a NavigationContainer and describe the screens:

JSX
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator initialRouteName="Home">
        <Stack.Screen name="Home" component={HomeScreen} options={{ title: 'Overview' }} />
        <Stack.Screen name="Details" component={DetailsScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

There are three parts. The container owns the navigation state and must wrap everything once. The navigator (Stack.Navigator) manages the pile. Each screen has a unique name and a component. The first screen listed (or the one named in initialRouteName) is the bottom of the stack.

Every screen component receives a navigation prop, which is your remote control:

JSX
function HomeScreen({ navigation }) {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>Home</Text>
      <Button title="Open details" onPress={() => navigation.navigate('Details')} />
    </View>
  );
}

Newer React Navigation versions (7 and later) also offer a static configuration API that builds the same navigator from one object. The concepts below are identical in both styles, so we use the component style here because it is the one you will see in most existing code.

Moving around the stack

Five methods cover nearly everything:

  • navigate(name, params?) goes to a screen. If you are already on a screen with that name, React Navigation updates its params instead of stacking a duplicate. Otherwise it adds the screen to the top.
  • push(name, params?) always adds a new copy on top, even when the same screen is already showing. Use it for "drill down into another item of the same kind", such as a profile that links to another profile.
  • goBack() removes the top screen. On Android the hardware back button does the same.
  • replace(name, params?) swaps the top screen for another one, so Back skips it. Good for a login screen that should not be reachable again.
  • popToTop() drops everything above the first screen.

There is also pop(count) to go back several screens at once and popTo(name) to return to a specific earlier screen. In React Navigation 7, navigate no longer walks back to an older screen of the same name; use popTo for that. In version 6 and earlier, navigate could do both, so check which version a tutorial was written for.

Five moves on the stack

navigate Go to a screen by name.
push Always add another copy.
goBack Remove the top screen.
replace Swap the top screen.
1 / 2
A stack navigator you can drive (stand-in)

Press navigate('Details') twice: the second press does nothing new, because you are already on Details. Press push('Details') twice instead and the depth grows each time.

Header options

The native stack draws a header for every screen. You customise it with options, either per screen or for the whole navigator:

JSX
<Stack.Navigator
  screenOptions={{
    headerStyle: { backgroundColor: '#1e293b' },
    headerTintColor: '#ffffff',
    headerTitleStyle: { fontWeight: '700' },
  }}
>
  <Stack.Screen
    name="Home"
    component={HomeScreen}
    options={{
      title: 'Overview',
      headerRight: () => <Button title="Info" onPress={() => alert('Hi')} />,
    }}
  />
  <Stack.Screen name="Details" component={DetailsScreen} options={{ headerBackTitle: 'Back', animation: 'slide_from_bottom' }} />
  <Stack.Screen name="Welcome" component={WelcomeScreen} options={{ headerShown: false }} />
</Stack.Navigator>

The ones you will use most are title, headerShown, headerRight and headerLeft (custom buttons), headerStyle and headerTintColor (colors), headerLargeTitle (iOS large titles), presentation: 'modal' (slide up as a sheet) and animation (transition style). Options can also be a function of { route, navigation } when they depend on params, and a screen can change its own header at runtime with navigation.setOptions({ title: 'New title' }).

Header options as data (stand-in)

Notice the merge order in resolveOptions: navigator-wide screenOptions first, then the screen's own options, then anything set at runtime. The last one wins, which is also how the real library resolves it.

Good habits

  • Keep screen names unique and in one place. Typos in navigate('Detials') fail at runtime; the typed navigation in Route Params and Typed Navigation turns them into compile errors.
  • Do not keep big objects in the stack. Pass an id and load the data in the target screen.
  • Use replace or conditional screens for login flows, so Back cannot return to a screen that no longer makes sense. See Deep Linking and Authentication Flows.
  • Remember a screen stays mounted when you push another on top of it, so its state survives and its effects keep running. Use focus events or the useFocusEffect hook for work that should only happen while the screen is visible.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You are on the Details screen and call navigation.push('Details'). What happens?

    push always adds a new instance on top. navigate would only update params when you are already on a screen with that name.
  2. 2. Which method removes the current screen from history so Back cannot return to it?

    replace swaps the top screen for another one. goBack also removes the top screen, but it shows the previous screen, it does not open a new one.
  3. 3. Where does the navigation state live?

    The NavigationContainer owns the state tree for all navigators below it. Screens only receive a navigation object to change it.
  4. 4. How do you hide the header for one screen only?

    Per-screen options override screenOptions. headerShown: false removes the header for that screen.

Summary

  • A stack navigator keeps a pile of screens, shows the top one and supplies a header with a back button.
  • Wrap the app in one NavigationContainer, create a navigator with createNativeStackNavigator, and declare each screen with a unique name and a component.
  • Use navigate, push, goBack, replace and popToTop (plus pop and popTo) to move; navigate does not duplicate the current screen, push does.
  • Header looks and behavior come from screenOptions (all screens) and options (one screen), and can change at runtime with navigation.setOptions.
  • On this site the real library is read-only and the TryIts are reducer-based stand-ins.

Next, send data between screens in Route Params and Typed Navigation.