You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: versioned_docs/version-5.x/configuring-links.md
+46-12
Original file line number
Diff line number
Diff line change
@@ -54,7 +54,7 @@ The `prefixes` option is needed to match the incoming deep links and strip the p
54
54
55
55
The `fallback` prop controls what's displayed when React Navigation is trying to resolve the initial deep link URL.
56
56
57
-
> Note: Deep link integration uses React Native's `Linking.getInitialUrl()` under the hood. Currently there seems to be bug ([facebook/react-native#25675](https://github.com/facebook/react-native/issues/25675)) which results in it never resolving on Android. you add a timeout to avoid getting stuck forever, but it means that the link might not be handled in some cases.
57
+
> Note: Deep link integration uses React Native's `Linking.getInitialUrl()` under the hood. Currently there seems to be bug ([facebook/react-native#25675](https://github.com/facebook/react-native/issues/25675)) which results in it never resolving on Android. We add a timeout to avoid getting stuck forever, but it means that the link might not be handled in some cases.
58
58
59
59
## Mapping path to route names
60
60
@@ -153,7 +153,7 @@ function App() {
153
153
}
154
154
```
155
155
156
-
Here you have a stack navigator in the root, and inside the `Home` screen of the root stack, you have a tab navigator with various screens. With this structure, let's say you want the path `/users/:id` to go to the `Profile` screen. you can express the nested config like so:
156
+
Here you have a stack navigator in the root, and inside the `Home` screen of the root stack, you have a tab navigator with various screens. With this structure, let's say you want the path `/users/:id` to go to the `Profile` screen. You can express the nested config like so:
157
157
158
158
```js
159
159
{
@@ -189,7 +189,7 @@ It's important to note that the state object must match the hierarchy of nested
189
189
190
190
## Rendering an initial route
191
191
192
-
Sometimes you want to ensure that a certain screen will always be present as the first screen in the navigator's state. you can use the `initialRouteName` property to specify the screen to use for the initial screen.
192
+
Sometimes you want to ensure that a certain screen will always be present as the first screen in the navigator's state. You can use the `initialRouteName` property to specify the screen to use for the initial screen.
193
193
194
194
In the above example, if you want the `Notifications` screen to be the initial route in the navigator under `Home`, your config will look like this:
195
195
@@ -229,6 +229,43 @@ const state = {
229
229
230
230
Note that in this case, any params in the URL are only passed to the `Profile` screen which matches the path pattern `users/:id`, and the `Notifications` screen doesn't receive any params. If you want to have the same params in the `Notifications` screen, you can specify a [custom `getStateFromPath` function](use-linking.md#getstatefrompath) and copy those params.
231
231
232
+
## Matching exact paths
233
+
234
+
By default, paths defined for each screen are matched against the URL relative to their parent screen's path. Consider the following config:
235
+
236
+
```js
237
+
{
238
+
Home: {
239
+
path:'feed',
240
+
screens: {
241
+
Profile:'users/:id',
242
+
},
243
+
},
244
+
}
245
+
```
246
+
247
+
Here, you have a `path` property defined for the `Home` screen, as well as the child `Profile` screen. The profile screen specifies the path `users/:id`, but since it's nested inside a screen with the path `feed`, it'll try to match the pattern `feed/users/:id`.
248
+
249
+
This will result in the URL `/feed` navigating to `Home` screen, and `/feed/users/cal` navigating to the `Profile` screen.
250
+
251
+
In this case, it makes more sense to navigate to the `Profile` screen using a URL like `/users/cal`, rather than `/feed/users/cal`. To achieve this, you can override the relative matching behavior to `exact` matching:
252
+
253
+
```js
254
+
{
255
+
Home: {
256
+
path:'feed',
257
+
screens: {
258
+
Profile: {
259
+
path:'users/:id',
260
+
exact:true,
261
+
},
262
+
},
263
+
},
264
+
}
265
+
```
266
+
267
+
With `exact` property set to `true`, `Profile` will ignore the parent screen's `path` config and you'll be able to navigate to `Profile` using a URL like `users/cal`.
268
+
232
269
## Omitting a screen from path
233
270
234
271
Sometimes, you may not want to have the route name of a screen in the path. For example, let's say you have a `Home` screen and our navigation state looks like this:
@@ -293,15 +330,14 @@ There are some constraints to consider when using nested navigators in the linki
293
330
294
331
1.**Using `initialRouteName` makes the screen always appear in the state of a navigator.** It's not possible to pass params to the initial screen through the URL by default, unless the URL explicitly maps to the screen. So make sure that your initial route doesn't take any params or specify `initialParams`.
295
332
296
-
2.**Having multiple screens of a nested navigator present in the state object is not possible through a one-part URL string.** you also cannot provide a URL like (for the above configuration) `/user/home`, because it would be resolved to `HomeStack->Profile->HomeStack->Home`. If you want to get rid of the second `HomeStack`, you can provide an explicit config for the `Home` screen in the first level of config nesting (remember to provide a different path string for each occurrence of a screen in the config):
333
+
2.**Having multiple screens of a nested navigator present in the state object is not possible in a single URL.** you also cannot provide a URL like (for the above configuration) `/user/home`, because it would be resolved to `HomeStack->Profile->HomeStack->Home`. If you want to get rid of the second `HomeStack`, you can provide an explicit config for the `Home` screen in the first level of config nesting (remember to provide a different path string for each occurrence of a screen in the config):
297
334
298
335
```js
299
336
constconfig= {
300
337
HomeStack: {
301
338
path:'stack',
302
-
initialRouteName:'Profile',
339
+
initialRouteName:'Feed',
303
340
screens: {
304
-
Home:'home',
305
341
Profile:'user',
306
342
},
307
343
},
@@ -310,9 +346,9 @@ There are some constraints to consider when using nested navigators in the linki
310
346
};
311
347
```
312
348
313
-
Then `/user/first` will resolve to `HomeStack->Profile->Home`.
349
+
Then `/user/home` will resolve to `HomeStack->Profile->Home`.
314
350
315
-
you can also make the config not include nested navigator, which will make the URL even longer, but maybe a bit less confusing.
351
+
You can also make the config not include nested navigator, which will make the URL even longer, but maybe a bit less confusing.
316
352
317
353
```js
318
354
constconfig= {
@@ -366,12 +402,11 @@ But what if you want to have parameters in the URL, like the user id of the pers
366
402
367
403
With the above config, in order to get to `Home` or `Profile` screen, you need to have `/stack` in the URL (`/stack/home` and `/stack/user`). But it'll be much better if you could go to the `Home` screen with `/home` and `Profile` screen with `/profile`.
368
404
369
-
you can achieve the behavior by using nested navigators in your `config`. The syntax looks like that:
405
+
You can achieve the behavior by using nested navigators in your `config`. The syntax looks like that:
370
406
371
407
```js
372
408
config = {
373
409
HomeStack: {
374
-
path:'stack',
375
410
screens: {
376
411
Home:'home',
377
412
Profile:'user',
@@ -383,14 +418,13 @@ config = {
383
418
384
419
As you can see, `Home` and `Profile` are now nested in the `screens` property of `HomeStack`. This means that when you pass the `/home` URL, it will be resolved to a `HomeStack`->`Home` state object (similarly for `/user` it would be `HomeStack`->`Profile`).
385
420
386
-
Here, the `HomeStack` property now contains a config object, and if you want to navigate straight to it, you have to provide it with the `path` property (`/stack` will go to `HomeStack`). The config can go as deep as you want, e.g. if `Home` was a navigator, you could make it an object with `screens` property, and put more screens or navigators inside it, making the URL string much more readable.
421
+
Here, the `HomeStack` property now contains a config object. The config can go as deep as you want, e.g. if `Home` was a navigator, you could make it an object with `screens` property, and put more screens or navigators inside it, making the URL string much more readable.
387
422
388
423
What if you wanted a specific screen to used as the initial screen in the navigator? For example, if you had a URL that would open `Home` screen, you would like to be able to navigate to `Profile` from it by using navigation's `navigation.goBack()` method. It is possible by defining `initialRouteName` for a navigator. It would look like this:
0 commit comments