Version: 5.x

useLinking

The useLinking hook lets us handle deep links in our apps. You probably want to use the linking prop on NavigationContainer instead of using this hook directly.

Example:

import * as React from 'react';
import { ScrollView } from 'react-native';
import { useLinking } from '@react-navigation/native';
export default function App() {
const ref = React.useRef();
const { getInitialState } = useLinking(ref, {
prefixes: ['https://mychat.com', 'mychat://'],
config: {
Chat: 'feed/:sort',
},
});
const [isReady, setIsReady] = React.useState(false);
const [initialState, setInitialState] = React.useState();
React.useEffect(() => {
getInitialState()
.catch(() => {})
.then(state => {
if (state !== undefined) {
setInitialState(state);
}
setIsReady(true);
});
}, [getInitialState]);
if (!isReady) {
return null;
}
return (
<NavigationContainer initialState={initialState} ref={ref}>
{/* content */}
</NavigationContainer>
);
}

See deep linking guide for a complete guide on how to configure deep linking.

Options

prefixes

URL prefixes to handle. You can provide multiple prefixes to support custom schemes as well as universal links.

Only URLs matching these prefixes will be handled. The prefix will be stripped from the URL before parsing.

Example:

useLinking(ref, {
prefixes: ['https://mychat.com', 'mychat://'],
config: {
Chat: 'feed/:sort',
},
});

This is only supported on iOS and Android.

config

Config to fine-tune how to parse the path. The config object should represent the structure of the navigators in the app.

For example, if we have Catalog screen inside Home screen and want it to handle the item/:id pattern:

{
Home: {
screens: {
Catalog: {
path: 'item/:id',
parse: {
id: Number,
},
},
},
},
}

The options for parsing can be an object or a string:

{
Catalog: 'item/:id',
}

When a string is specified, it's equivalent to providing the path option.

The path option is a pattern to match against the path. Any segments starting with : are recognized as a param with the same name. For example item/42 will be parsed to { name: 'item', params: { id: '42' } }.

The initialRouteName option ensures that the route name passed there will be present in the state for the navigator, e.g. for config:

{
Home: {
initialRouteName: 'Feed',
screens: {
Catalog: {
path: 'item/:id',
parse: {
id: Number,
},
},
Feed: 'feed',
},
},
}

and URL : /item/42, the state will look like this:

{
routes: [
{
name: 'Home',
state: {
index: 1,
routes: [
{
name: 'Feed'
},
{
name: 'Catalog',
params: { id: 42 },
},
],
},
},
],
}

The parse option controls how the params are parsed. Here, you can provide the name of the param to parse as a key, and a function which takes the string value for the param and returns a parsed value:

{
Catalog: {
path: 'item/:id',
parse: {
id: id => parseInt(id, 10),
},
},
}

If no custom function is provided for parsing a param, it'll be parsed as a string.

Different segments of the same path can be handled by different parts of the config. For example, say we have the URL /rooms/chat/jane. We can provide the following config to handle it:

{
Rooms: 'rooms',
Chat: 'chat/:user'
}

This will result in the following navigation state:

{
routes: [
{
name: 'Rooms',
state: {
routes: [
{
name: 'Chat',
params: { user: 'jane' },
},
],
},
},
],
}

enabled

Optional boolean to enable or disable the linking integration. Defaults to true.

getStateFromPath

You can optionally override the way React Navigation parses deep links to a state object by providing your own implementation.

Example:

useLinking(ref, {
prefixes: ['https://mychat.com', 'mychat://'],
config: {
Chat: 'feed/:sort',
},
getStateFromPath(path, config) {
// Return a state object here
// You can also reuse the default logic by importing `getStateFromPath` from `@react-navigation/native`
}
});

getPathFromState

You can optionally override the way React Navigation serializes state objects to link by providing your own implementation. This is necessary for proper web support if you have specified getStateFromPath.

Example:

useLinking(ref, {
prefixes: ['https://mychat.com', 'mychat://'],
config: {
Chat: 'feed/:sort',
},
getPathFromState(state, config) {
// Return a path string here
// You can also reuse the default logic by importing `getPathFromState` from `@react-navigation/native`
}
});