|
| 1 | +--- |
| 2 | +id: hello-react-navigation-static |
| 3 | +title: Static configuration |
| 4 | +sidebar_label: Static configuration |
| 5 | +--- |
| 6 | + |
| 7 | +In a web browser, there are multiple **pages** and you can **link to** the pages using an anchor (`<a>`) tag. Similarly, in React Native, you have multiple **screens** and you can **navigate** between them. |
| 8 | + |
| 9 | +React Navigation provides different types of navigators, such as the stack navigator, tab navigator, drawer navigator, etc. Each navigator provides a different way of transitioning between screens. They have a similar API for configuring them. |
| 10 | + |
| 11 | +The stack navigator is the most commonly used navigator. It resembles how you would expect multiple pages to work in a web browser. In this guide, let's start by demonstrating how to configure the native stack navigator. |
| 12 | + |
| 13 | +## Installing the native stack navigator library |
| 14 | + |
| 15 | +The libraries we've installed so far are the building blocks and shared foundations for navigators, and each navigator in React Navigation lives in its own library. To use the native stack navigator, we need to install [`@react-navigation/native-stack`](https://github.com/react-navigation/react-navigation/tree/main/packages/native-stack) : |
| 16 | + |
| 17 | +```bash npm2yarn |
| 18 | +npm install @react-navigation/native-stack@next |
| 19 | +``` |
| 20 | + |
| 21 | +> 💡 `@react-navigation/native-stack` depends on `react-native-screens` and the other libraries that we installed in [Getting started](getting-started.md). If you haven't installed those yet, head over to that page and follow the installation instructions. |
| 22 | +
|
| 23 | +## Creating a native stack navigator |
| 24 | + |
| 25 | +`createNativeStackNavigator` is a function that takes a configuration object containing the screens and customization options. The screens are React Components that render the content displayed by the navigator. |
| 26 | + |
| 27 | +```js |
| 28 | +// In App.js in a new project |
| 29 | + |
| 30 | +import * as React from 'react'; |
| 31 | +import { View, Text } from 'react-native'; |
| 32 | +import { createStaticNavigation } from '@react-navigation/native'; |
| 33 | +import { createNativeStackNavigator } from '@react-navigation/native-stack'; |
| 34 | + |
| 35 | +function HomeScreen() { |
| 36 | + return ( |
| 37 | + <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}> |
| 38 | + <Text>Home Screen</Text> |
| 39 | + </View> |
| 40 | + ); |
| 41 | +} |
| 42 | + |
| 43 | +const RootStack = createNativeStackNavigator({ |
| 44 | + screens: { |
| 45 | + Home: HomeScreen, |
| 46 | + }, |
| 47 | +}); |
| 48 | + |
| 49 | +const Navigation = createStaticNavigation(RootStack); |
| 50 | + |
| 51 | +function App() { |
| 52 | + return <Navigation />; |
| 53 | +} |
| 54 | + |
| 55 | +export default App; |
| 56 | +``` |
| 57 | + |
| 58 | +If you run this code, you will see a screen with an empty navigation bar and a grey content area containing your `HomeScreen` component (shown above). The styles you see for the navigation bar and the content area are the default configuration for a stack navigator, we'll learn how to configure those later. |
| 59 | + |
| 60 | +> The casing of the route name doesn't matter -- you can use lowercase `home` or capitalized `Home`, it's up to you. We prefer capitalizing our route names. |
| 61 | +
|
| 62 | +### Configuring the navigator |
| 63 | + |
| 64 | +All of the route configuration is specified as props to our navigator. We haven't passed any props to our navigator, so it just uses the default configuration. |
| 65 | + |
| 66 | +Let's add a second screen to our native stack navigator and configure the `Home` screen to render first: |
| 67 | + |
| 68 | +```js |
| 69 | +function DetailsScreen() { |
| 70 | + return ( |
| 71 | + <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}> |
| 72 | + <Text>Details Screen</Text> |
| 73 | + </View> |
| 74 | + ); |
| 75 | +} |
| 76 | + |
| 77 | +const RootStack = createNativeStackNavigator({ |
| 78 | + initialRouteName: 'Home', |
| 79 | + screens: { |
| 80 | + Home: HomeScreen, |
| 81 | + Details: DetailsScreen, |
| 82 | + }, |
| 83 | +}); |
| 84 | + |
| 85 | +const Navigation = createStaticNavigation(RootStack); |
| 86 | + |
| 87 | +function App() { |
| 88 | + return <Navigation />; |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +Now our stack has two _routes_, a `Home` route and a `Details` route. A route can be specified by using the `Screen` component. The `Screen` component accepts a `name` prop which corresponds to the name of the route we will use to navigate, and a `component` prop which corresponds to the component it'll render. |
| 93 | + |
| 94 | +Here, the `Home` route corresponds to the `HomeScreen` component, and the `Details` route corresponds to the `DetailsScreen` component. The initial route for the stack is the `Home` route. Try changing it to `Details` and reload the app (React Native's Fast Refresh won't update changes from `initialRouteName`, as you might expect), notice that you will now see the `Details` screen. Then change it back to `Home` and reload once more. |
| 95 | + |
| 96 | +### Specifying options |
| 97 | + |
| 98 | +Each screen in the navigator can specify some options for the navigator, such as the title to render in the header. To specify the options, we'll change how we have specified the screen component: |
| 99 | + |
| 100 | +```js |
| 101 | +const RootStack = createNativeStackNavigator({ |
| 102 | + initialRouteName: 'Home', |
| 103 | + screens: { |
| 104 | + Home: { |
| 105 | + screen: HomeScreen, |
| 106 | + }, |
| 107 | + Details: DetailsScreen, |
| 108 | + }, |
| 109 | +}); |
| 110 | +``` |
| 111 | + |
| 112 | +Now, we can add an `options` property: |
| 113 | + |
| 114 | +```js |
| 115 | +const RootStack = createNativeStackNavigator({ |
| 116 | + initialRouteName: 'Home', |
| 117 | + screens: { |
| 118 | + Home: { |
| 119 | + screen: HomeScreen, |
| 120 | + options: { |
| 121 | + title: 'Overview', |
| 122 | + } |
| 123 | + }, |
| 124 | + Details: DetailsScreen, |
| 125 | + }, |
| 126 | +}); |
| 127 | +``` |
| 128 | + |
| 129 | +Sometimes we will want to specify the same options for all of the screens in the navigator. For that, we can pass add a `screenOptions` property to the configuration. |
| 130 | + |
| 131 | +```js |
| 132 | +const RootStack = createNativeStackNavigator({ |
| 133 | + initialRouteName: 'Home', |
| 134 | + screenOptions: { |
| 135 | + headerStyle: { backgroundColor: 'tomato' }, |
| 136 | + }, |
| 137 | + screens: { |
| 138 | + Home: { |
| 139 | + screen: HomeScreen, |
| 140 | + options: { |
| 141 | + title: 'Overview', |
| 142 | + } |
| 143 | + }, |
| 144 | + Details: DetailsScreen, |
| 145 | + }, |
| 146 | +}); |
| 147 | +``` |
| 148 | + |
| 149 | +Here we have specified a `headerStyle` property. This will customize the styles of the header in all of the screens of the navigator. |
| 150 | + |
| 151 | +## What's next? |
| 152 | + |
| 153 | +The natural question at this point is: "how do I go from the `Home` route to the `Details` route?". That is covered in the [navigating section](navigating.md) under fundamentals. |
| 154 | + |
| 155 | +## Summary |
| 156 | + |
| 157 | +- React Native doesn't have a built-in API for navigation like a web browser does. React Navigation provides this for you, along with the iOS and Android gestures and animations to transition between screens. |
| 158 | +- `createNativeStackNavigator` is a function that takes the screens configuration and renders our content. |
| 159 | +- Each property under screens refers to the name of the route, and the value is the component to render for the route. |
| 160 | +- To specify what the initial route in a stack is, provide an `initialRouteName` option for the navigator. |
| 161 | +- To specify screen-specific options, we can specify an `options` property, and for common options, we can specify `screenOptions`. |
0 commit comments