Getting started with App Bridge React

Provider

Anchor link to section titled "Provider"

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.

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.

Using a custom router

Anchor link to section titled "Using 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.

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.

Using App Bridge React with Polaris React

Anchor link to section titled "Using 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.

Accessing the App Bridge context directly

Anchor link to section titled "Accessing 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.

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.

Use Context.Consumer to get access to the App Bridge client app in render props.

ClientRouter

Anchor link to section titled "ClientRouter"

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.

In App.jsx, set up a custom history object and pass it into a Router component.

In the Router component, pass the history prop into the useClientRouting hook.

Pass the history prop into the ClientRouter component.

RoutePropagator

Anchor link to section titled "RoutePropagator"

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.

1. Import useRoutePropagation from @shopify/app-bridge-react.
2. Call useRoutePropagation with a location parameter.
3. Configure the routes according to your custom routing solution.

Import or create a location object and pass it onto a RoutePropagator component.