Skip to main content

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. Polaris 2.0 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.


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 What changes in Polaris 2.0What changes in Polaris 2.0

Polaris 2.0 changes how components look, not how you use them. Compared with Polaris 1.1, which polaris-1.js and the unversioned polaris.js serve, Polaris 2.0 has the same components with the same properties, accepted values, events, methods, and slots. It doesn't remove, rename, or deprecate any of them, so markup that works with Polaris 1.1 works with Polaris 2.0 unchanged.

The values that your app sets keep working in both appearances. For example, tone on s-badge, variant on s-button, format on s-table-header, and the spacing properties of s-stack and s-box accept the same values as in Polaris 1.1, and spacing keywords such as base resolve to the same sizes. App Bridge elements, such as s-app-nav, aren't part of Polaris, so the Polaris version doesn't change them.

Anchor to What's new in the APIWhat's new in the API

Polaris 2.0 adds the following. You don't need any of them to update.

ComponentAddition
s-thumbnailThe loading property. Set it to lazy so that a thumbnail requests its image only when it's shown, such as in a menu that isn't open. The default, eager, requests the image immediately.
s-text-fieldThe icon property accepts every icon name that s-icon accepts. In Polaris 1.1, it accepted 30 fewer names.
s-sectionThe supplemental slot accepts s-tooltip.

Anchor to What changes in appearanceWhat changes in appearance

How Polaris 2.0 looks depends on the Shopify admin around your app:

  • In the current Shopify admin, Polaris 2.0 looks the same as Polaris 1.1.
  • In the updated Shopify admin, every component takes the updated appearance: the ShopifyInter typeface, new colors for each tone, and larger corner radii. For example, buttons are pill-shaped.

In the updated Shopify admin, the following components also change their layout or fill:

ComponentChange in the updated Shopify admin
s-sectionA section at the top level of the page renders its heading above the card, on the page background, instead of inside the card. The heading is also larger and lighter. A section in the aside slot of s-page renders without a card, and its heading is lighter and gray.
s-buttonIn the page content, a button with the default or secondary variant has a gray fill instead of a border. With tone="critical", that button has a tinted red fill.
s-bannerA banner that isn't in a section renders as a tinted block without a shadow, as a banner in a section does. In the current Shopify admin, it renders as a card with a shadow, and its heading has a colored background.

To see how these changes affect your own screens, compare them in both appearances, as Step 3 describes.


  • Build your app's UI with Polaris web components. If your app still renders @shopify/polaris React components, then it keeps the current appearance until you migrate them to web components.
  • If your app is built from the React Router template, then use version 2.1.0 or later of @shopify/shopify-app-react-router, which requires Node.js 22 or later. Apps created from older versions of the template, and some sample apps, use version 1.x. Version 2.0.0 is a major release with breaking changes, so upgrade from version 1.x first.
  • 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

In apps scaffolded with Shopify CLI, the AppProvider component from @shopify/shopify-app-react-router renders the Polaris and App Bridge script tags for the routes that it wraps, 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.

Some versions of the template also load Polaris on the login page, app/routes/auth.login/route.tsx (route.jsx in the JavaScript template), with a script tag or an AppProvider of its own. polarisUrl in app/routes/app.tsx doesn't apply to that page, so the login page can load a different release from the rest of your app. If your app has this route, then load Polaris there with a script tag that uses the same URL as polarisUrl. The login page is a separate document from the routes that AppProvider wraps, so this tag doesn't load a second bundle. Don't use AppProvider on the login page: from version 2.0.0, it always loads App Bridge too, and the login page opens outside the Shopify admin.

This section uses the file names of the TypeScript template. In the JavaScript template, the same files end in .jsx instead of .tsx and .js instead of .ts, like app/routes/app.jsx and app/shopify.server.js.

// app/polaris.ts
export const POLARIS_URL = 'https://cdn.shopify.com/shopifycloud/polaris-2.js';
// app/routes/app.tsx
import {POLARIS_URL} from '../polaris';

export default function App() {
const {apiKey} = useLoaderData<typeof loader>();

return (
<AppProvider apiKey={apiKey} polarisUrl={POLARIS_URL}>
<Outlet />
</AppProvider>
);
}
// app/shopify.server.ts
import {POLARIS_URL} from './polaris';

const shopify = shopifyApp({
apiKey: process.env.SHOPIFY_API_KEY,
// ...the other options that your app sets
polarisUrl: POLARIS_URL,
});

export const addDocumentResponseHeaders = shopify.addDocumentResponseHeaders;

polarisUrl is a top-level option of the configuration object that you pass to shopifyApp. shopify.addDocumentResponseHeaders reads it, and the template's app/entry.server.tsx calls that function to add the Link header to your app's document responses. React Router's build fails if a component imports a value from a .server module, so AppProvider can't read the URL from app/shopify.server.ts. Keep the URL in a module that both files import, such as app/polaris.ts, so that the two settings always match. To check the Link header that your app sends, see Load exactly one Polaris bundle.

Both settings need version 2.1.0 or later of @shopify/shopify-app-react-router. If your app uses version 1.x, then upgrade from version 1.x first. Both settings are optional, and their default depends on the package's major version. In versions 2.1.0 to 3.x, 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. In version 4.0.0 and later, both fall back to polaris-2.js, so an app that leaves them unset loads Polaris 2. To learn which release each URL serves, see Available versions. To learn when the default changed, see the @shopify/shopify-app-react-router changelog.

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 Upgrade from version 1.xUpgrade from version 1.x

Apps created from older versions of the React Router template, and some sample apps, use version 1.x of @shopify/shopify-app-react-router, which doesn't support polarisUrl. To check which version your app uses, run the following command:

Terminal

npm ls @shopify/shopify-app-react-router

If your app uses version 1.x, then upgrade the package before you set polarisUrl. Version 2.0.0 is a major release with breaking changes. The following steps cover the changes that affect apps built from the template. The steps use the TypeScript file names. In the JavaScript template, the files end in .jsx and .js instead.

  1. Use Node.js 22 or later, because version 2.0.0 doesn't support Node.js 20. The template sets engine-strict=true in .npmrc, so on Node.js 20 the install command in the next step fails with an EBADENGINE error. Update the places that set your Node.js version. For an app created from an older version of the template, make the same changes as the current template:

    • In package.json, change engines.node from >=20.19 <22 || >=22.12 to >=22.12.
    • In Dockerfile, change FROM node:20-alpine to FROM node:22-alpine.

    If your CI or your hosting provider sets a Node.js version, then update it there too.

  2. Upgrade @shopify/shopify-app-react-router and your session storage package together, so that both packages use the same major version of @shopify/shopify-api. If your app uses Prisma session storage, as the template does, then run the following command:

    Terminal

    npm install @shopify/shopify-app-react-router@latest @shopify/shopify-app-session-storage-prisma@latest

    If you upgrade only @shopify/shopify-app-react-router, then npm installs a second copy of @shopify/shopify-api and doesn't warn you. For example, version 9.x of @shopify/shopify-app-session-storage-prisma needs version 13 of @shopify/shopify-api, but version 2.x of @shopify/shopify-app-react-router uses version 14.

    To upgrade to a specific version of @shopify/shopify-app-react-router rather than the latest version, find that version's column in the following table, and use the session storage version from the same column. Other session storage packages are the DynamoDB, KV, memory, MongoDB, MySQL, PostgreSQL, Redis, and SQLite packages:

    @shopify/shopify-app-react-router2.x3.x and 4.x
    @shopify/shopify-api1415
    @shopify/shopify-app-session-storage-prisma10.x11.x
    @shopify/shopify-app-session-storage-drizzle5.x6.x
    Other session storage packages7.x8.x

    To check that your app installs only one copy of @shopify/shopify-api, run npm ls @shopify/shopify-api.

    If the Session model in prisma/schema.prisma has no refreshToken field, then add the refresh token fields to it. Older versions of the template don't have these fields. Version 8.0.0 and later of @shopify/shopify-app-session-storage-prisma store them with every session, so without them, your app fails with PrismaClientValidationError: Unknown argument refreshToken when it stores a session:

    prisma/schema.prisma

    model Session {
    // ...
    refreshToken String?
    refreshTokenExpires DateTime?
    }

    Then run the following command. It creates a migration, applies it to your development database, and regenerates Prisma Client. Commit the new migration, so that prisma migrate deploy applies it when you deploy:

    Terminal

    npx prisma migrate dev --name add_session_refresh_token
  3. In app/routes/app.tsx, remove the embedded prop from AppProvider. AppProvider no longer accepts it.

  4. Move the login form into the _index route. In version 1.x, the template's app/routes/auth.login route renders its form inside <AppProvider embedded={false}>, and that AppProvider is the only thing that loads Polaris on the login page. Version 2.0.0 removes the embedded prop. The changelog shows a diff that removes AppProvider and keeps the <s-page> markup, but then the login page loads no Polaris: <s-text-field> never becomes an input, so the form can't send a shop domain. The _index route uses plain HTML form elements, so its login form doesn't need Polaris:

    1. Move error.server.tsx from app/routes/auth.login to app/routes/_index.

    2. In app/routes/_index/route.tsx, add an action that calls login:

      app/routes/_index/route.tsx

      import type {ActionFunctionArgs} from 'react-router';

      import {login} from '../../shopify.server';
      import {loginErrorMessage} from './error.server';

      export const action = async ({request}: ActionFunctionArgs) => {
      const errors = loginErrorMessage(await login(request));

      return {errors};
      };
    3. In the same file, remove action="/auth/login" from the <Form>, so that the form submits to its own route. Then show the errors that the action returns. The template's _index route has no place for them, so without this change, the form shows no message when the shop domain is empty or invalid. Read errors with useActionData, and show errors.shop under the field in place of the example domain:

      app/routes/_index/route.tsx

      import {redirect, Form, useActionData, useLoaderData} from 'react-router';

      // ...

      export default function App() {
      const {showForm} = useLoaderData<typeof loader>();
      const actionData = useActionData<typeof action>();
      const errors = actionData?.errors;

      return (
      <div className={styles.index}>
      <div className={styles.content}>
      {/* ... */}
      {showForm && (
      <Form className={styles.form} method="post">
      <label className={styles.label}>
      <span>Shop domain</span>
      <input className={styles.input} type="text" name="shop" />
      <span>{errors?.shop ?? 'e.g: my-shop-domain.myshopify.com'}</span>
      </label>
      <button className={styles.button} type="submit">
      Log in
      </button>
      </Form>
      )}
      {/* ... */}
      </div>
      </div>
      );
      }

      login checks only the format of the shop domain, not whether the store exists. For a domain with a valid format, login redirects to Shopify and returns no error, so your app shows no message for a store that doesn't exist.

    4. Delete the app/routes/auth.login route.

    After you delete the route, /auth/login is still the package's login path, because the package builds the login path from authPathPrefix, which defaults to /auth. A request for /auth/login now reaches app/routes/auth.$.tsx, which calls authenticate.admin, so the response is an HTTP 500 error with the text Detected call to shopify.authenticate.admin() from configured login path ('/auth/login'), please make sure to call shopify.login() from that route instead.

    Your app and the Shopify admin don't request this path, so you can leave it as it is. Don't change authPathPrefix to move the login path: the option is also the prefix of the OAuth callback and the other authentication paths, and it must match your auth.$ route. If people still open /auth/login from old links or bookmarks, then add a route that redirects them to the login form in _index:

    app/routes/auth.login.tsx

    import type {LoaderFunctionArgs} from 'react-router';
    import {redirect} from 'react-router';

    export const loader = ({request}: LoaderFunctionArgs) => {
    return redirect(`/${new URL(request.url).search}`);
    };

    If you keep the app/routes/auth.login route instead, then replace <AppProvider embedded={false}> with a Polaris script tag of the route's own. Don't keep AppProvider on this route: from version 2.0.0, it always loads App Bridge and needs an apiKey, and the login page runs outside the Shopify admin. Use the same URL as polarisUrl, so that the login page loads the same Polaris release as the rest of your app. The login route doesn't render AppProvider, so this tag is the only Polaris script on that page:

    app/routes/auth.login/route.tsx

    export default function Auth() {
    // ...
    return (
    <>
    <script src="https://cdn.shopify.com/shopifycloud/polaris-2.js" />
    <s-page>
    <Form method="post">{/* ... */}</Form>
    </s-page>
    </>
    );
    }
  5. If your shopifyApp configuration sets isEmbeddedApp, then remove it.

  6. If your webhook handlers read subTopic, then remove it and use webhook filters instead.

Versions 3.0.0 and 4.0.0 have breaking changes of their own. Version 3.0.0 removes eventId and resourceId from events webhooks, and version 4.0.0 changes the default Polaris URL, as described earlier in this section. To review every breaking change, see the @shopify/shopify-app-react-router changelog. To compare your app with the template's own upgrade, see the template's upgrade pull request.

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.

<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.js"></script>
</head>
// 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.js" />
</head>
</html>
);
}
// app/layout.tsx
export default function RootLayout({children}: {children: React.ReactNode}) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<meta name="shopify-api-key" content={process.env.SHOPIFY_API_KEY} />
{/* eslint-disable-next-line @next/next/no-sync-scripts */}
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js" />
{/* eslint-disable-next-line @next/next/no-sync-scripts */}
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js" />
</head>
<body>{children}</body>
</html>
);
}

Whichever framework renders the tags, follow these rules:

  • Replace %SHOPIFY_API_KEY% with your app's client ID. A server-rendered app can read the client ID from the SHOPIFY_API_KEY environment variable, which Shopify CLI provides to your app's processes.
  • Put the shopify-api-key meta tag before the app-bridge.js script tag. App Bridge reads the meta tag when its script runs.
  • Make app-bridge.js the first script that blocks parsing, and don't add async, defer, or type="module" to it. If the tag has one of these attributes, then App Bridge throws an error and doesn't start. If another blocking script comes first, then App Bridge logs a warning. Scripts that have async, defer, or type="module", such as the scripts that Next.js adds, can come before it.
  • Put the Polaris script tag after the app-bridge.js script tag.
  • Render both tags as plain <script> elements in the HTML that your server sends. A script component that adds the tag in the browser, such as next/script in Next.js, makes the script async, so App Bridge doesn't start.

In a Next.js app that uses the App Router, render the tags in your root layout, as the Next.js sample does. Three details are specific to Next.js:

  • The eslint-config-next rules report each tag as @next/next/no-sync-scripts, because the tags block rendering. App Bridge needs to block rendering, so the sample turns off the rule for these two lines.
  • Polaris 2.0 adds a class to the <html> element as it loads, before React hydrates the page. In development, React reports the class as a hydration mismatch. The sample sets suppressHydrationWarning on <html>, which stops the report.
  • Next.js prerenders a layout that doesn't read request data when you run next build, so the build reads SHOPIFY_API_KEY. Set the variable in your build environment as well as at runtime.

In a Next.js app that uses the Pages Router, render the same tags in the Head component of pages/_document.tsx.

Anchor to Match your TypeScript typesMatch your TypeScript types

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.js, then install @shopify/polaris-types@^2.0.0. Update the script tag and the package together when you move to a new release.

Anchor to Apps on the release candidateApps on the release candidate

If your app loads the Polaris 2.0 release candidate, polaris-2.0-rc.js, then move it to a stable URL. The release candidate URL doesn't follow the stable release: it keeps serving the last release candidate, 2.0.0-rc.3, and doesn't get the fixes that later 2.x releases include. Replace it with polaris-2.js wherever your app sets the Polaris URL: in your script tag, or in both polarisUrl settings. To stay on the 2.0 release instead of following the channel, use polaris-2.0.js.

Update your TypeScript types in the same change. The @shopify/polaris-types@^2.0.0-rc.0 range that matches the release candidate also installs 2.0.0 and later 2.x releases. If you move to polaris-2.js, then install @shopify/polaris-types@^2.0.0. If you move to polaris-2.0.js, then install @shopify/polaris-types@~2.0.0. If your app stays on the release candidate for now, then pin the package to the exact version, 2.0.0-rc.3.

The release candidate's reference became the Polaris 2.0 reference when 2.0 went stable, so /docs/api/app-home/v2.0-rc no longer has its own pages. Use the Polaris 2.0 reference instead. To learn how release candidates and stable releases work, see Stable releases and release candidates.


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. To check which script your app loads and the exact release that it runs, see Check which version your app loads.

To check the preload, open your app in the Shopify admin, and then open your browser's developer tools. In the Network panel, select the document request for your app, such as /app?embedded=1&shop=.... In its response headers, the Link header lists the scripts that the browser preloads. The Polaris entry looks like <https://cdn.shopify.com/shopifycloud/polaris-2.js>; rel="preload"; as="script", and its URL must match the URL of the Polaris script request. Only document requests that include the shop query parameter, like the ones that the Shopify admin makes when it opens your app, get the header. Pages that open without that parameter, such as your login page, and the data requests that your app makes when it navigates on the client don't have it.

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

Polaris doesn't provide its design tokens as a public CSS API. The --p-* custom properties that you see in your browser's developer tools are private to Polaris. Their names end in a suffix that changes between Polaris releases, such as --p-color-bg-fill-info-secondary-f4125 in Polaris 1.1.0 and --p-color-bg-fill-info-secondary-6e076 in Polaris 2.0.0, and a component can read a different property in each appearance. CSS that reads or overrides these properties stops working after an update, and the browser doesn't report an error.

Values that you copy out of @shopify/polaris-tokens are fixed, so they don't follow the appearance that the Shopify admin renders. Your own fixed values have the same problem: a fixed value can match only one appearance, and your app needs to be correct in both, as Step 3 describes.

To make UI that your app owns follow both appearances, build it from Polaris web components and style it with their properties. Polaris resolves those properties for the appearance that the Shopify admin renders:

  • Replace a custom card with a section.
  • Build a custom container with a box, and set its background, border, borderRadius, and padding properties instead of writing CSS for them.
  • Replace a custom status pill with a badge, and choose the tone that matches its meaning. Polaris components don't accept custom colors.
  • Replace a styled native input with the matching Polaris form field, such as a date field.

Then remove the CSS that reads, overrides, or copies Polaris token values. Keep your own CSS for layout and for elements that don't imitate Polaris.

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.

Polaris custom properties are private, so Polaris doesn't provide a public font token. To learn more, see Find CSS built on Polaris token values. Polaris also doesn't set a font on the <html> or <body> element. Instead, each Polaris component passes its font, text size, and text color to the elements that you place inside it. Your own elements inside s-page, such as custom cards or widgets, already inherit the font of the appearance that the Shopify admin renders, so remove any font-family that your CSS sets on them or on a wrapper around them.

An element outside s-page doesn't inherit the Polaris font. To give the same font to a fixed element outside s-page, such as a fixed footer, wrap the element in s-box. The element stays fixed to the viewport.

HTML

<s-page heading="Products">
<!-- Your own elements here inherit the Polaris font. -->
</s-page>
<s-box>
<div class="app-footer">
<!-- Fixed footer content. -->
</div>
</s-box>

Browsers give native form controls their own font, so a <button>, <input>, <select>, or <textarea> that you render yourself doesn't inherit the Polaris font. Set font: inherit on these elements.

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, which is 0px when nothing floats there.

App Bridge also adds an invisible spacer at the end of the <body> element: a body::after pseudo-element that's as tall as the overlay. The spacer lets in-flow content scroll above the overlay, so most apps need no change. App Bridge doesn't pad the <body> element itself, so its computed padding-bottom stays 0px. If your app scrolls inside its own container instead of the page, then add var(--shopify-safe-area-inset-bottom, 0px) to the bottom padding of that container.

The spacer doesn't move elements that use position: fixed, so your app draws its own fixed-bottom elements under the overlay. How you use the variable depends on the shape of the element:

  • For a floating element, such as a floating action button or a chat button, add the variable to its bottom offset. The element moves up above the overlay.
  • For a full-width bar, such as a sticky footer, keep bottom: 0 and add the variable to its padding-bottom. The bar's background reaches the bottom edge, and its content stays above the overlay. If you move a full-width bar up with the bottom offset instead, then page content scrolls into view in the gap below the bar.

CSS

.floating-button {
position: fixed;
right: 16px;
bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
}

.sticky-footer {
position: fixed;
right: 0;
bottom: 0;
left: 0;
padding: 12px 16px calc(12px + var(--shopify-safe-area-inset-bottom, 0px));
}

A full-width bar also covers the end of your page content. Reserve space for the bar at the end of the content, for example with padding-bottom on your main element. When the page scrolls, the App Bridge spacer already reserves the height of the overlay, so reserve only the height of the bar without the variable.

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.



Was this page helpful?