App provider

App provider is a required component that enables sharing global settings throughout the hierarchy of your application.


AppProvider works by default without any additional options passed to it.

Drag to resize example


The API key for your application from the Partner dashboard
Inner content of the application
For toggling features
Forces a redirect to the relative admin path when not rendered in an iframe
TranslationDictionary | TranslationDictionary[]
A locale object or array of locale objects that overrides default translations. If specifying an array then your fallback language dictionaries should come first, followed by your primary language dictionary
A custom component to use for all links used by Polaris components
The current shop’s origin, provided in the session from the Shopify API (to be provided without the https://)
Custom logos and colors provided to select components

Best practices

The app provider component is required to use Polaris. Without it, the components in your application will not function correctly. You must wrap the root (the top) of your application in the app provider component. We’ve created several examples to show how that’s done.

Using translations

Translations are provided in the locales folder. When using Polaris, you are able to import translations from all languages supported by the core Shopify product and consume them through the i18n prop.

If a project has only one locale, then you can pass the JSON content from the locale file into AppProvider.

import AppProvider from '@shopify/polaris';
// en.json is English. Replace with fr.json for French, etc
import translations from '@shopify/polaris/locales/en.json';

function App() {
  return <AppProvider i18n={translations}>{/* App content */}</AppProvider>;

If a project supports multiple locales, then load them dynamically using @shopify/react-i18n. This ensures that you load only the translations you need.

import AppProvider from '@shopify/polaris';
// en.json is English. Replace with fr.json for French, etc
import translations from '@shopify/polaris/locales/en.json';
import {useI18n} from '@shopify/react-i18n';

function App() {
  const [i18n] = useI18n({
    id: 'Polaris',
    fallback: translations,
    translations(locale) {
      return import(
        /* webpackChunkName: "Polaris-i18n", webpackMode: "lazy-once" */ `@shopify/polaris/locales/${locale}.json`
      ).then((dictionary) => dictionary && dictionary.default);

  // i18n.translations is an array of translation dictionaries, where the first
  // dictionary is the desired language, and the second is the fallback.
  // AppProvider however expects that the first dictionary is the fallback
  // and the second is the desired language. Thus we need to reverse the array
  // to ensure the dictionaries are in the order desired by AppProvider.
  // The slice is to ensure we don't manipulate the original translations array
  // as reverse() modifies the array in-place.
  return (
    <AppProvider i18n={i18n.translations.slice().reverse()}>
      {/* App content */}

Using linkComponent

By default Polaris renders <Link> elements (and action objects) as <a> tags. That works well for simple one-page demos. However for more complex multi-page applications that use a router such as react-router you will want links to use the components provided by your router. If you don't then every link will be an <a> tag and thus trigger a whole page refresh instead of navigating client-side.

The linkComponent prop allows you to customise how links behave within Polaris by allowing you to inject your router's own Link component. The following example demonstrates using react-router's Link component.

import {BrowserRouter, Link as ReactRouterLink} from 'react-router-dom';

function App() {
  return (
      <AppProvider linkComponent={Link}>
        {/* App content including your <Route> components */}

const IS_EXTERNAL_LINK_REGEX = /^(?:[a-z][a-z\d+.-]*:|\/\/)/;

function Link({children, url = '', external, ref,}) {
  // react-router only supports links to pages it can handle itself. It does not
  // support arbirary links, so anything that is not a path-based link should
  // use a reglar old `a` tag
  if (external || IS_EXTERNAL_LINK_REGEX.test(url)) { = '_blank';
    rest.rel = 'noopener noreferrer';
    return (
      <a href={url} {}>

  return (
    <ReactRouterLink to={url} {}>

Initializing the Shopify App Bridge (deprecated)

When using Polaris, you don’t need to go through the initialization of the Shopify App Bridge as described in the Shopify Help Center. Instead, configure the connection to the Shopify admin through the app provider component, which wraps all components in an embedded app. The app provider component initializes the Shopify App Bridge using the apiKey and shopOrigin that you provide. The apiKey and the shopOrigin attributes are required. Find the API key for your app in the Apps section of your Shopify Partner Dashboard. Learn how to get and store the shop origin in the Shopify Help Center.

  <AppProvider apiKey="YOUR_API_KEY" shopOrigin="SHOP_ORIGIN" i18n={{}}>
      onSelection={({selection}) => {
        console.log('Selected products: ', selection);
        this.setState({open: false});
      onCancel={() => this.setState({open: false})}

Deprecation rationale

As of v3.17.0, using apiKey and shopOrigin on AppProvider to initialize the Shopify App Bridge is deprecated. Support for this will be removed in v5.0 as the underlying Shopify App Bridge library will be removed from Polaris React. Learn more about the deprecation rationale. Use Provider from @shopify/app-bridge-react instead.

Access to the Shopify App Bridge instance (deprecated)

To provide access to your initialized Shopify App Bridge instance, we make it available through React’s context. The example below demonstrates how to access the appBridge object from React’s context, in order to use the Redirect action to navigate:

import React from 'react';
import {render} from 'react-dom';
import {AppProvider, _SECRET_INTERNAL_APP_BRIDGE_CONTEXT} from '@shopify/polaris';
import {Redirect} from '@shopify/app-bridge/actions';

function MyApp() {
  const appBridge = useContext(_SECRET_INTERNAL_APP_BRIDGE_CONTEXT)

  redirectToSettings() {
    const redirect = Redirect.create(appBridge);

    // Go to {appOrigin}/settings
    redirect.dispatch(Redirect.Action.APP, '/settings');

  render() {
    return null;

    <MyApp />

Deprecation rationale

As of v3.17.0, using the Shopify App Bridge instance in context is deprecated. Support for this will be removed in v5.0 as the underlying Shopify App Bridge library will be removed from Polaris React. More information can be found here. Use the Shopify App Bridge directly instead.

Testing components

You must include Polaris context in your tests when you use Polaris components.

To make this easier for you, we’ve provided:

  • a createPolarisContext() function to create the Polaris context for you
  • a polarisContextTypes variable that contains all the necessary context types
  • a fully-working example app with Jest and Enzyme you can reference