---
title: Update your app for Polaris 2
description: >-
  Move your embedded app to Polaris 2.0 so that it matches the updated Shopify
  admin appearance, then check the parts of your UI that Polaris doesn't
  control.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-home/polaris2'
  md: 'https://shopify.dev/docs/apps/build/app-home/polaris2.md'
api_name: app-home
---

# Update your app for Polaris 2

Shopify is updating the Shopify admin to introduce a new frame, new navigation, and a new visual appearance. This update changes the appearance of every surface in the admin. The new Polaris 2.0 release candidate for App Home updates the web components so that your app matches the look and feel of this new Shopify admin experience.

Shopify styles your embedded app with the same mechanism it uses for the Shopify admin's own pages. If you build your app's UI entirely with [Polaris web components](https://shopify.dev/docs/api/app-home/v2.0-rc/web-components), then you don't need to change your app's code to adopt the updated styling; you only need to load Polaris 2.0. An app that stays on Polaris 1 keeps the current appearance, and so does any part of your UI that still renders `@shopify/polaris` React components.

In this guide, you'll learn how to update your app to Polaris 2.0, audit the parts of your UI that Polaris doesn't control, and check the result against both the updated and the current Shopify admin.

**Caution:**

Polaris 2.0 for App Home is currently available only as a release candidate (`rc`) version. Release candidates can change during the soak period, and those changes might affect your app. Test your app now to make sure that it works with Polaris 2.0, and switch over when the release candidate is promoted to a stable version.

***

## How it works

The Shopify admin signals which styling to use through App Bridge, and Polaris web components match the appearance of the Shopify admin as they initialize. Your app takes no part in this. There's no API to call and no configuration to set.

Polaris 1 doesn't contain the updated styling at all, so an app that loads Polaris 1 renders the current appearance regardless of what the Shopify admin around it is doing. Polaris 2.0 carries both and selects between them at runtime.

***

## Requirements

* Build your app's UI with [Polaris web components](https://shopify.dev/docs/api/app-home/v2.0-rc/web-components). If your app still renders `@shopify/polaris` React components, then it keeps the current appearance until you [migrate them to web components](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react).
* Install your app on a development store so you can preview changes.

***

## Step 1: Update your Polaris version

How you load Polaris 2.0 depends on how your app loads Polaris today. Apps built from the React Router template set the URL in their configuration. Apps that render their own script tag change the URL in the tag.

To learn more about how Polaris releases and channels work, see [Adding Polaris to your app](https://shopify.dev/docs/api/app-home/v2.0-rc/web-components/versioning#adding-polaris-to-your-app).

### Apps built from the React Router template

Apps scaffolded with Shopify CLI have no script tag of their own. The `AppProvider` component from `@shopify/shopify-app-react-router` renders the Polaris and App Bridge script tags for you, and your server configuration adds a `Link` header that preloads Polaris. Set `polarisUrl` in both places, and keep the two values identical. If the values differ, then the browser preloads one Polaris bundle while your app loads another.

##### React Router

```tsx
// app/routes/app.tsx
<AppProvider
  apiKey={apiKey}
  polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
  <Outlet />
</AppProvider>
```

##### Server configuration

```ts
// app/shopify.server.ts
const shopify = shopifyApp({
  // ...
  polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js',
});
```

Both settings need version 2.1.0 or later of `@shopify/shopify-app-react-router`. Both are optional, and both fall back to the unversioned `polaris.js`, which never serves Polaris 2.x, so an app that leaves them unset stays on Polaris 1.

Set the version in these two places rather than adding a Polaris script tag of your own. A second tag would load a second Polaris bundle and cause a failure.

### Apps with their own script tag

If your app renders its own Polaris script tag, then change the version in the tag.

##### HTML

```html
<head>
  <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  <script src="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"></script>
</head>
```

##### Remix

```tsx
// app/root.tsx
export default function App() {
  return (
    <html>
      <head>
        <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
        <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js" />
        <script src="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js" />
      </head>
    </html>
  );
}
```

### Match your Type​Script types

If you use TypeScript, then match [`@shopify/polaris-types`](https://www.npmjs.com/package/@shopify/polaris-types) to the release that your app loads, so that your types describe the components that your app renders. If you load `polaris-2.0-rc.js`, then install `@shopify/polaris-types@^2.0.0-rc.0`. A plain `^2.0` range resolves to nothing while 2.0 is still a release candidate, because npm ranges exclude prereleases. Update the script tag and the package together when you move to a stable release.

***

## Step 2: Audit your app

Polaris components restyle themselves. Anything in your UI that Polaris doesn't control stays as it is, so if your app uses custom components or styling, then you'll need to update those parts so that your app's appearance stays consistent with the rest of the Shopify admin. The same is true if your app uses React Polaris components.

Work through the following checks.

### Load exactly one Polaris bundle

Confirm that your app loads a single Polaris script tag, on the version you intend. Loading two scripts causes your app to throw an error. Check for a stale tag left behind by a bundler alias or a shared layout. Load the Polaris tag after `app-bridge.js`, as the samples in Step 1 do, so that App Bridge publishes the Shopify admin's signal before Polaris initializes. If your app uses `AppProvider`, then check that its `polarisUrl` still matches the one in your server configuration.

### Replace remaining Polaris React components

Any component that `@shopify/polaris` still renders keeps the current appearance and won't follow the updated Shopify admin. A page that mixes React Polaris with web components will therefore render different components with different styles when you update to Polaris 2.0. To replace the React components, refer to [Migrate from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react).

### Find CSS built on Polaris token values

Custom CSS that reads Polaris custom properties, or that hardcodes values copied out of `@shopify/polaris-tokens`, pins those rules to the old palette. Replace copied values with your own tokens to match the updated Polaris 2.0 styling, or remove any custom components and replace them with Polaris web components.

### Check your fonts

The updated Shopify admin uses ShopifyInter. If your app hardcodes Inter, or sets its own font stack over the top of Polaris, then it keeps the old type. Polaris 2.0 loads the correct faces for the appearance that the Shopify admin is rendering, so you can remove font loading that exists only to support Polaris.

### Compare custom components against Polaris ones

Hand-rolled UI that you matched to the current appearance by eye looks visibly off next to restyled Polaris components. Look at anything you built to match Polaris styling, such as custom cards, badges, banners, and empty states.

### Position fixed-bottom elements above host UI

The updated Shopify admin floats UI over the bottom of your app's viewport, such as the Sidekick bar, or navigation controls on mobile web. App Bridge reports the height of that overlay as the `--shopify-safe-area-inset-bottom` CSS custom property, and it pads the `<body>` element for you, so most apps need no change. If your app positions its own fixed-bottom elements, such as sticky footers or floating action buttons, then your app draws them under the overlay. Position them with `var(--shopify-safe-area-inset-bottom, 0px)`, which is `0px` when nothing floats there.

This check doesn't depend on which Polaris version your app loads, because App Bridge sets the property either way. To learn more, see [Safe area insets](https://shopify.dev/docs/api/app-home/v2.0-rc/apis/authentication-and-data/environment-api#safe-area-insets) in the Environment API reference.

### Walk your main flows

Open your app and walk the paths your users take, including empty states, error states, and any screen that appears only after a long setup.

***

## Step 3: Test both appearances

During the rollout, some users see the updated Shopify admin and others see the current one, so your app needs to be correct in both. After your app loads Polaris 2.0, it follows whichever appearance the surrounding Shopify admin renders, so testing means viewing your app in the Shopify admin on each rather than changing anything in your app. Shopify enables the updated appearance in development stores, so you can test your app against it there.

To ensure that your app still renders correctly when the new appearance isn't enabled, test it in a store that hasn't received the update.

***

## Next steps

[App Home reference\
\
](https://shopify.dev/docs/api/app-home/v2.0-rc)

[Explore web components, APIs, App Bridge web components, and page patterns.](https://shopify.dev/docs/api/app-home/v2.0-rc)

[Migrate from Polaris React\
\
](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react)

[Move your app from `@shopify/polaris` React components to Polaris web components.](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react)

[App design guidelines\
\
](https://shopify.dev/docs/apps/design)

[Follow our UX guidelines so that your app feels at home in the Shopify admin.](https://shopify.dev/docs/apps/design)

***