Skip to content

Commit 781a54b

Browse files
committed
Updat linking docs
1 parent 418c354 commit 781a54b

File tree

2 files changed

+46
-189
lines changed

2 files changed

+46
-189
lines changed

blog/2020-05-01-web-support.md

-177
This file was deleted.

versioned_docs/version-5.x/configuring-links.md

+46-12
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ The `prefixes` option is needed to match the incoming deep links and strip the p
5454

5555
The `fallback` prop controls what's displayed when React Navigation is trying to resolve the initial deep link URL.
5656

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.
5858
5959
## Mapping path to route names
6060

@@ -153,7 +153,7 @@ function App() {
153153
}
154154
```
155155

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:
157157

158158
```js
159159
{
@@ -189,7 +189,7 @@ It's important to note that the state object must match the hierarchy of nested
189189

190190
## Rendering an initial route
191191

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.
193193

194194
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:
195195

@@ -229,6 +229,43 @@ const state = {
229229

230230
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.
231231

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+
232269
## Omitting a screen from path
233270

234271
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
293330

294331
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`.
295332

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):
297334

298335
```js
299336
const config = {
300337
HomeStack: {
301338
path: 'stack',
302-
initialRouteName: 'Profile',
339+
initialRouteName: 'Feed',
303340
screens: {
304-
Home: 'home',
305341
Profile: 'user',
306342
},
307343
},
@@ -310,9 +346,9 @@ There are some constraints to consider when using nested navigators in the linki
310346
};
311347
```
312348

313-
Then `/user/first` will resolve to `HomeStack->Profile->Home`.
349+
Then `/user/home` will resolve to `HomeStack->Profile->Home`.
314350

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.
316352

317353
```js
318354
const config = {
@@ -366,12 +402,11 @@ But what if you want to have parameters in the URL, like the user id of the pers
366402

367403
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`.
368404

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:
370406

371407
```js
372408
config = {
373409
HomeStack: {
374-
path: 'stack',
375410
screens: {
376411
Home: 'home',
377412
Profile: 'user',
@@ -383,14 +418,13 @@ config = {
383418

384419
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`).
385420

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.
387422

388423
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:
389424

390425
```js
391426
config = {
392427
HomeStack: {
393-
path: 'stack',
394428
initialRouteName: 'Profile',
395429
screens: {
396430
Home: 'home',

0 commit comments

Comments
 (0)