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.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import React from 'react';

import ReactDOM from 'react-dom';

import {Provider, Loading} from '@shopify/app-bridge-react';

function MyApp() {

return (

</Provider>

);

}

const root = document.createElement('div');

document.body.appendChild(root);

ReactDOM.createRoot(root).render(<MyApp />);

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.

import {useMemo} from 'react';

import {useLocation, useNavigate, BrowserRouter} from 'react-router-dom';

import {Provider} from '@shopify/app-bridge-react';

import Routes from './Routes';

export function MyApp() {

const navigate = useNavigate();

const location = useLocation();

const history = useMemo(

() => ({replace: (path) => navigate(path, {replace: true})}),

[navigate],

);

const router = useMemo(

() => ({

location,

history,

}),

[location, history],

);

return (

<Provider

config={config}

router={router}

</Provider>

);

}

export default function AppWrapper() {

return (

</BrowserRouter>

);

}

Anchor to Provider PropsProvider Props

Name	Type	Description	Required
config	`AppConfig`	Your application configuration	Yes
router	`RouterConfig`	Custom router configuration	No

Anchor to AppConfigAppConfig

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 RouterConfigRouterConfig

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.

import React from 'react';

import ReactDOM from 'react-dom';

import {Provider, Loading} from '@shopify/app-bridge-react';

import {AppProvider, Card} from '@shopify/polaris';

function MyApp() {

return (

</Provider>

</AppProvider>

);

}

const root = document.createElement('div');

document.body.appendChild(root);

ReactDOM.createRoot(root).render(<MyApp />);

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)

Anchor to useAppBridgeuseAppBridge

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

import React, {useEffect} from 'react';

import ReactDOM from 'react-dom';

import {Provider, useAppBridge} from '@shopify/app-bridge-react';

function MyFunctionalComponent() {

const app = useAppBridge();

useEffect(() => {

const getState = async () => {

const state = await app.getState();

console.log(state);

};

getState();

}, [app]);

return Hello world!;

};

function MyApp() {

return (

</Provider>

);

}

const root = document.createElement('div');

document.body.appendChild(root);

ReactDOM.createRoot(root).render(<MyApp />);

Anchor to useContextuseContext

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

import React, {useContext} from 'react';

import {Provider, Context} from '@shopify/app-bridge-react';

function MyFunctionalComponent() {

const app = useContext(Context);

if (app) {

// Do something with App Bridge `app` instance...

app.getState().then(state => console.log(state));

}

return (Hello world!);

};

function MyApp() {

return (

</Provider>

);

}

const root = document.createElement('div');

document.body.appendChild(root);

ReactDOM.createRoot(root).render(<MyApp />);

Anchor to App Context with RenderPropsApp Context with RenderProps

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

Context.Consumer

import React from 'react';

import {Provider, Context} from '@shopify/app-bridge-react';

function MyComponent() {

return (

<Context.Consumer>

{app => {

// Do something with App Bridge `app` instance...

if (app) {

app.getState().then(state => console.log(state));

}

return (Hello world!);

}}

</Context.Consumer>

);

};

function MyApp() {

return (

</Provider>

);

}

const root = document.createElement('div');

document.body.appendChild(root);

ReactDOM.createRoot(root).render(<MyApp />);

Anchor to ClientRouterClientRouter

Note

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], hook`useClientRouting` hook

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

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

// App.jsx

import React from 'react';

import {useNavigate, BrowserRouter} from 'react-router-dom';

import {Provider} from '@shopify/app-bridge-react';

import MyRouter from '../MyRouter';

export default function MyApp() {

const navigate = useNavigate();

const history = useMemo(

() => ({replace: (path) => navigate(path, {replace: true})}),

[navigate],

);

return (

</Provider>

</BrowserRouter>

);

}

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

// MyRouter.jsx

import React from 'react';

import {useClientRouting} from '@shopify/app-bridge-react';

export default function MyRouter(props) {

const {history} = props;

useClientRouting(history);

return null;

}

Anchor to [object Object], component`<ClientRouter />` component

Pass the history prop into the ClientRouter component.

import React from 'react';

import {useNavigate, BrowserRouter} from 'react-router-dom';

import {ClientRouter, Provider} from '@shopify/app-bridge-react';

export default function MyApp() {

const navigate = useNavigate();

const history = useMemo(

() => ({replace: (path) => navigate(path, {replace: true})}),

[navigate],

);

return (

</Provider>

</BrowserRouter>

);

}

Anchor to RoutePropagatorRoutePropagator

Note

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], hook`useRoutePropagation` hook

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

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import React from 'react';

import {Routes, Route, useLocation} from 'react-router-dom';

import {Provider as AppBridgeProvider} from '@shopify/app-bridge-react';

import {useRoutePropagation} from '@shopify/app-bridge-react';

export default function MyApp() {

const location = useLocation();

useRoutePropagation(location);

return (

{ /* other routes */ }

</Routes>

</AppBridgeProvider>

);

}

Anchor to [object Object]`<RoutePropagator />`

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

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import React from 'react';

import {Routes, Route, useLocation} from 'react-router-dom';

import {Provider as AppBridgeProvider} from '@shopify/app-bridge-react';

import {RoutePropagator as AppBridgeRoutePropagator} from '@shopify/app-bridge-react';

export default function MyApp() {

const location = useLocation();

return (

{ /* other routes */ }

</Routes>

</AppBridgeProvider>

);

}

Was this page helpful?

Anchor to ProviderProvider

Anchor to Example codeExample code

Anchor to Using a custom routerUsing a custom router

Anchor to Example codeExample code

Anchor to Provider PropsProvider Props

Anchor to AppConfigAppConfig

Anchor to RouterConfigRouterConfig

Anchor to Using App Bridge React with Polaris ReactUsing App Bridge React with Polaris React

Anchor to Accessing the App Bridge context directlyAccessing the App Bridge context directly

Anchor to useAppBridgeuseAppBridge

Anchor to useContextuseContext

Anchor to App Context with RenderPropsApp Context with RenderProps

Anchor to ClientRouterClientRouter

Anchor to [object Object], hookuseClientRouting hook

Anchor to [object Object], component<ClientRouter /> component

Anchor to RoutePropagatorRoutePropagator

Anchor to [object Object], hookuseRoutePropagation hook

Anchor to [object Object]<RoutePropagator />

Anchor to [object Object], hook`useClientRouting` hook

Anchor to [object Object], component`<ClientRouter />` component

Anchor to [object Object], hook`useRoutePropagation` hook

Anchor to [object Object]`<RoutePropagator />`