Skip to main content

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.


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.

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 config={config}>
<Loading />
</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.

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}
>
<Routes />
</Provider>
);
}

export default function AppWrapper() {
return (
<browserRouter />
<MyApp />
</BrowserRouter>
);
}

NameTypeDescriptionRequired
configAppConfigYour application configurationYes
routerRouterConfigCustom router configurationNo

NameTypeDescriptionRequired
apiKeystringThe client ID from Shopify Partner DashboardYes
hoststringThe hostname for the current shop. Learn moreYes
forceRedirectbooleanUse 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

NameTypeDescriptionRequired
history{replace: (path) => navigate(path, {replace: boolean})}An object to control the history of the browserYes
locationLocationAn object with the location infomation of the current pageYes

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 (
<AppProvider>
<Provider config={config}>
<Loading />
<Card />
</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)

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 <span>Hello world!</span>;
};

function MyApp() {
return (
<Provider config={config}>
<MyFunctionalComponent />
</Provider>
);
}
const root = document.createElement('div');
document.body.appendChild(root);
ReactDOM.createRoot(root).render(<MyApp />);

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 (<span>Hello world!</span>);
};

function MyApp() {
return (
<Provider config={config}>
<MyFunctionalComponent />
</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 (<span>Hello world!</span>);
}}
</Context.Consumer>
);
};

function MyApp() {
return (
<Provider config={config}>
<MyComponent />
</Provider>
);
}

const root = document.createElement('div');
document.body.appendChild(root);
ReactDOM.createRoot(root).render(<MyApp />);

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], hookuseClientRouting 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 (
<browserRouter />
<Provider config={config}>
<MyRouter history={history} />
</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 (
<browserRouter />
<Provider config={config}>
<ClientRouter history={history} />
</Provider>
</BrowserRouter>
);
}

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.

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

  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.
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 (
<AppBridgeProvider config={config}>
<Routes>
<Route path="/" element={<span>Hello world!</span>} />
{ /* 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 (
<AppBridgeProvider config={config}>
<AppBridgeRoutePropagator location={location} />
<Routes>
<Route path="/" element={<span>Hello world!</span>} />
{ /* other routes */ }
</Routes>
</AppBridgeProvider>
);
}

Was this page helpful?