Guides
Plan-enterprise-icon
Expo Application Services
API Reference

Linking

expo-linking provides utilities for your app to interact with other installed apps using deep links. It also provides helper methods for constructing and parsing deep links into your app. This module is an extension of the React Native Linking module.
For a more comprehensive explanation of how to use expo-linking, refer to the Linking guide.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-success-icon

Installation

Terminal
→ npx expo install expo-linking

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

API

import * as Linking from 'expo-linking';

Hooks

useURL()

Returns the initial URL followed by any subsequent changes to the URL.

Returns

  • Undo-iconstring | null

Returns the initial URL or null.

Methods

Linking.canOpenURL(url)

NameTypeDescription
urlstring

The URL that you want to test can be opened.

Determine whether or not an installed app can handle a given URL. On web this always returns true because there is no API for detecting what URLs can be opened.

A Promise object that is fulfilled with true if the URL can be handled, otherwise it false if not.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist.

Linking.collectManifestSchemes()

Collect a list of platform schemes from the manifest.

This method is based on the Scheme modules from @expo/config-plugins which are used for collecting the schemes before prebuilding a native app.

  • iOS: scheme -> ios.scheme -> ios.bundleIdentifier
  • Android: scheme -> android.scheme -> android.package
  • Undo-iconstring[]

Linking.createURL(path, namedParameters)

NameTypeDescription
pathstring

Addition path components to append to the base URL.

namedParameters
(optional)
CreateURLOptions

Additional options object.

Default: {}

Helper method for constructing a deep link into your app, given an optional path and set of query parameters. Creates a URI scheme with two slashes by default.

The scheme in bare and standalone must be defined in the Expo config (app.config.js or app.json) under expo.scheme.

Examples

  • Bare: <scheme>://path - uses provided scheme or scheme from Expo config scheme.
  • Standalone, Custom: yourscheme://path
  • Web (dev): https://localhost:19006/path
  • Web (prod): https://myapp.com/path
  • Expo Client (dev): exp://128.0.0.1:19000/--/path
  • Expo Client (prod): exp://exp.host/@yourname/your-app/--/path
  • Undo-iconstring

A URL string which points to your app with the given deep link information.

Linking.getInitialURL()

Get the URL that was used to launch the app if it was launched by a link.

The URL string that launched your app, or null.

Linking.hasConstantsManifest()

Ensure the user has linked the expo-constants manifest in bare workflow.

  • Undo-iconboolean
Warning-icon
Deprecated. An alias for createURL(). This method is deprecated and will be removed in a future SDK version.

Linking.makeUrl(path, queryParams, scheme)

NameTypeDescription
path
(optional)
string

addition path components to append to the base URL.

Default: ''
queryParams
(optional)
ParsedQs

An object with a set of query parameters. These will be merged with any Expo-specific parameters that are needed (e.g. release channel) and then appended to the URL as a query string.

scheme
(optional)
string

Optional URI protocol to use in the URL <scheme>:///, when undefined the scheme will be chosen from the Expo config (app.config.js or app.json).

Create a URL that works for the environment the app is currently running in. The scheme in bare and standalone must be defined in the app.json under expo.scheme.

Examples

  • Bare: empty string
  • Standalone, Custom: yourscheme:///path
  • Web (dev): https://localhost:19006/path
  • Web (prod): https://myapp.com/path
  • Expo Client (dev): exp://128.0.0.1:19000/--/path
  • Expo Client (prod): exp://exp.host/@yourname/your-app/--/path
  • Undo-iconstring

A URL string which points to your app with the given deep link information.

Linking.openSettings()

Open the operating system settings app and displays the app’s custom settings, if it has any.

Linking.openURL(url)

NameTypeDescription
urlstring

A URL for the operating system to open, eg: tel:5555555, exp://.

Attempt to open the given URL with an installed app. See the Linking guide for more information.

A Promise that is fulfilled with true if the link is opened operating system automatically or the user confirms the prompt to open the link. The Promise rejects if there are no applications registered for the URL or the user cancels the dialog.

Linking.parse(url)

NameTypeDescription
urlstring

A URL that points to the currently running experience (e.g. an output of Linking.createURL()).

Helper method for parsing out deep link information from a URL.

A ParsedURL object.

Linking.parseInitialURLAsync()

Helper method which wraps React Native's Linking.getInitialURL() in Linking.parse(). Parses the deep link information out of the URL used to open the experience initially. If no link opened the app, all the fields will be null.

Info-icon

On the web it parses the current window URL.

A promise that resolves with ParsedURL object.

Linking.resolveScheme(options)

NameTypeDescription
options{ isSilent: boolean, scheme: string }-
  • Undo-iconstring
Only for:
Android-iconAndroid

Linking.sendIntent(action, extras)

NameTypeDescription
actionstring-
extras
(optional)
SendIntentExtras[]-

Launch an Android intent with extras.

Info-icon

Use IntentLauncher instead, sendIntent is only included in Linking for API compatibility with React Native's Linking API.

Event Subscriptions

Linking.addEventListener(type, handler)

NameTypeDescription
type'url'

The only valid type is 'url'.

handlerURLListener

An URLListener function that takes an event object of the type EventType.

Add a handler to Linking changes by listening to the url event type and providing the handler. It is recommended to use the useURL() hook instead.

Info-icon

An EmitterSubscription that has the remove method from EventSubscription

Warning-icon
Deprecated. Call remove() on the return value of addEventListener() instead.

Linking.removeEventListener(type, handler)

NameTypeDescription
type'url'

The only valid type is 'url'.

handlerURLListener

An URLListener function that takes an event object of the type EventType.

Remove a handler by passing the url event type and the handler.

Info-icon
  • Undo-iconvoid

Types

CreateURLOptions

NameTypeDescription
isTripleSlashed
(optional)
booleanShould the URI be triple slashed scheme:///path or double slashed scheme://path.
queryParams
(optional)
QueryParamsAn object of parameters that will be converted into a query string.
scheme
(optional)
stringURI protocol <scheme>:// that must be built into your native app.

EventType

NameTypeDescription
nativeEvent
(optional)
MessageEvent-
urlstring-

NativeURLListener()

NameTypeDescription
nativeEventMessageEvent-

ParsedURL

NameTypeDescription
hostnamestring | null-
pathstring | nullThe path into the app specified by the URL.
queryParamsQueryParams | nullThe set of query parameters specified by the query string of the url used to open the app.
schemestring | null-

QueryParams

  • ParsedQs

SendIntentExtras

NameTypeDescription
keystring-
valuestring | number | boolean-

URLListener()

NameTypeDescription
eventEventType-
  • Message-iconAsk a question on the forums about Linking
  • Github-iconView open bug reports for Linking
  • Code-iconView source code for Linking
  • Build-iconView package in npm Registry
  • Edit-iconEdit this page

Was this doc helpful?