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.

## 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](#provider-props).

### Example code

This example demonstrates setting up the app with a `Provider` and using the [Loading](/docs/api/app-bridge/previous-versions/actions/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](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app).


```jsx
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 />);
```

## 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](#clientrouter), along with the [route propagator](#routepropagator) to manage custom routing. In newer versions of App Bridge React, the `Provider` accepts an optional `router` prop and configures custom routing for you.

### Example 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.

```jsx
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>
  );
}
```

## Provider Props

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

### AppConfig

|Name|Type|Description|Required|
|---|---|---|---|
|apiKey|`string`|The client ID from Shopify Partner Dashboard|Yes|
|host|`string`|The hostname for the current shop. [Learn more](/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant)|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|

### RouterConfig

|Name|Type|Description|Required|
|---|---|---|---|
|history|`{replace: (path) => navigate(path, {replace: boolean})}`|An object to control the history of the browser|Yes|
|location|[`Location`](https://developer.mozilla.org/en-US/docs/Web/API/Location)|An object with the location infomation of the current page|Yes|

## Using App Bridge React with Polaris

App Bridge React is fully compatible with [Polaris](https://polaris.shopify.com).
To use them together, wrap your app in both Polaris’s `<AppProvider>` component and App Bridge React’s `<Provider>` component.

```jsx
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 />);
```

## 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)

### useAppBridge

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.

```jsx?title: "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 />);
```

### useContext

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.

```jsx?title: "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 />);
```

### App Context with RenderProps

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

```jsx?title: "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 />);
```

## ClientRouter

> 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](#using-a-custom-router) 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.

### `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](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app).


```jsx
// 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.

```jsx
// 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;
}
```

### `<ClientRouter />` component

Pass the `history` prop into the `ClientRouter` component.

```jsx
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>
  );
}
```

## RoutePropagator

> 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](#using-a-custom-router) 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](/docs/api/app-bridge/previous-versions/actions/navigation/history) to keep the parent URL in sync manually.

You can use `RoutePropagator` as a hook or a component.

### `useRoutePropagation` hook

1. Import `useRoutePropagation` from `@shopify/app-bridge-react`.
1. Call `useRoutePropagation` with a `location` parameter.
1. 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](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app).


```jsx
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>
  );
}
```


### `<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](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app).


```jsx
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>
  );
}
```