Getting started with App Bridge React
If you're using React in your project, then you should use the App Bridge React library. App Bridge React provides hooks and components that let you use App Bridge in a standard and familiar way inside your React application.
To get started, you need to add the App Bridge Provider and any custom routing features that you want to use.
Anchor to ProviderProvider
The App Bridge Provider
provides the app context for all the components within it. It accepts a config
object and an optional router
prop. For more information about props, refer to Provider props.
Anchor to Example codeExample code
This example demonstrates setting up the app with a Provider
and using the Loading component.
Import the Provider
from @shopify/app-bridge-react
and pass a config
object into it. You can then use App Bridge React components and hooks within the Provider
.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.
Anchor to Using a custom routerUsing a custom router
You may want to use a custom client-side router, such as react-router
, to manage navigation within your app. Prior to version 2.0.25
you would use the client router, along with the route propagator to manage custom routing. In newer versions of App Bridge React, the Provider
accepts an optional router
prop and configures custom routing for you.
Anchor to Example codeExample code
Passing in a router will allow you to bypass setting up the client router and the route propagator. If you are using React Router, ensure that the Provider
is a child of the router component.
Anchor to Provider PropsProvider Props
Name | Type | Description | Required |
---|---|---|---|
config | AppConfig | Your application configuration | Yes |
router | RouterConfig | Custom router configuration | No |
Anchor to AppConfigApp Config
Name | Type | Description | Required |
---|---|---|---|
apiKey | string | The client ID from Shopify Partner Dashboard | Yes |
host | string | The hostname for the current shop. Learn more | Yes |
forceRedirect | boolean | Use to toggle redirecting to the Shopify admin when the app is not opened inside the Shopify admin. Defaults to true in production. Defaults to false in dev environments. | No |
Anchor to RouterConfigRouter Config
Name | Type | Description | Required |
---|---|---|---|
history | {replace: (path) => navigate(path, {replace: boolean})} | An object to control the history of the browser | Yes |
location | Location | An object with the location infomation of the current page | Yes |
Anchor to Using App Bridge React with Polaris ReactUsing App Bridge React with Polaris React
App Bridge React is fully compatible with Polaris React.
To use them together, wrap your app in both Polaris React’s <AppProvider>
component and App Bridge React’s <Provider>
component.
Anchor to Accessing the App Bridge context directlyAccessing the App Bridge context directly
App Bridge React provides access to the App Bridge client app
instance using the React Context API.
Some ways to access the app context include:
useAppBridge
(recommended)useContext
(for Apps using version 1.24.0 and below)Context.Consumer
(using render props)
The useAppBridge
hook is available in version 1.25.0 and above. You can use this hook to access the App Bridge client app
in a functional component.
useAppBridge
Anchor to useContextuse Context
If you're using a version of App Bridge below 1.25.0 where the useAppBridge
hook isn't available, use React’s useContext
hook directly.
useContext
Anchor to App Context with RenderPropsApp Context with Render Props
Use Context.Consumer
to get access to the App Bridge client app
in render props.
Context.Consumer
Anchor to ClientRouterClient Router
Although the client router and route propagator utilies remain available in the current version of App Bridge React, we recommend avoiding the manual process of setting up these features. Instead, you can use the optional routing prop in the Provider to accomplish the same behavior.
By default, App Bridge applies URL changes from outside your app by updating the iframe URL. If your app uses client-side routing, such as React Router, then you need to override this behavior to avoid unnecessary full-page reloads. ClientRouter
prevents App Bridge from changing the iframe URL, and enables you provide a custom client-side router, for example react-router
, to handle navigation. Use ClientRouter with any routing system that provides a history.replace
method, which accepts a string for the updated path.
You can use ClientRouter
as a hook or a component.
Anchor to [object Object], hookuseClientRouting
hook
useClientRouting
hookIn App.jsx
, set up a custom history object and pass it into a Router
component.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.
In the Router
component, pass the history
prop into the useClientRouting
hook.
Anchor to [object Object], component<ClientRouter />
component
<ClientRouter />
componentPass the history
prop into the ClientRouter
component.
Anchor to RoutePropagatorRoute Propagator
Although the client router and route propagator utilies remain available in the current version of App Bridge React, we recommend avoiding the manual process of setting up these features. Instead, you can use the optional routing prop in the Provider to accomplish the same behavior.
When a user navigates inside an embedded app, the URL of the embedded app iframe changes. If the user reloads the page, then the navigation isn't reflected in the URL of the parent page. RoutePropagator
enables you synchronize a Shopify embedded app's URL with the parent page.
You can also use the App Bridge History API to keep the parent URL in sync manually.
You can use RoutePropagator
as a hook or a component.
Anchor to [object Object], hookuseRoutePropagation
hook
useRoutePropagation
hook- Import
useRoutePropagation
from@shopify/app-bridge-react
. - Call
useRoutePropagation
with alocation
parameter. - Configure the routes according to your custom routing solution.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.
Anchor to [object Object]<RoutePropagator />
<RoutePropagator />
Import or create a location
object and pass it onto a RoutePropagator
component.
In the following example, config
is a valid App Bridge configuration object. Learn more about configuring App Bridge.