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, 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.
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.
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.
Anchor to How it worksHow 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.
Anchor to RequirementsRequirements
- Build your app's UI with Polaris web components. If your app still renders
@shopify/polarisReact components, then it keeps the current appearance until you migrate them to web components. - Install your app on a dev store so you can preview changes.
Anchor to Step 1: Update your Polaris versionStep 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.
Anchor to Apps built from the React Router templateApps 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
// app/routes/app.tsx
<AppProvider
apiKey={apiKey}
polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
<Outlet />
</AppProvider>Server configuration
// 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.
Anchor to Apps with their own script tagApps with their own script tag
If your app renders its own Polaris script tag, then change the version in the tag.
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
// 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>
);
}Anchor to Match your TypeScript typesMatch your Type
If you use TypeScript, then match @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.
Anchor to Step 2: Audit your appStep 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.
Anchor to Load exactly one Polaris bundleLoad 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.
Anchor to Replace remaining Polaris React componentsReplace 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.
Anchor to Find CSS built on Polaris token valuesFind 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.
Anchor to Check your fontsCheck 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.
Anchor to Compare custom components against Polaris onesCompare 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.
Anchor to Position fixed-bottom elements above host UIPosition 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 in the Environment API reference.
Anchor to Walk your main flowsWalk 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.
Anchor to Step 3: Test both appearancesStep 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.
To test the updated appearance, use a dev store that has the Shopify admin's new design feature preview enabled. You choose a dev store's feature preview when you create it, so if you don't have a store with this preview enabled, then create a new one. To create the store with Shopify CLI, run shopify store create dev with the --feature-preview new_admin_design flag.
To test the current appearance, use any dev store that doesn't have the Shopify admin's new design.
