Skip to content

Polaris 2.0: what the release candidate brought and how to migrate your Shopify app

Update/ 17 min read

Polaris 2.0 went from release candidate to stable on October 22. What rc.1 changed, which URL to load, how to test it in a branch and what to migrate in your components.

  • Shopify
  • Migration
  • Shopify apps
In this article (8)
  1. What Polaris is, and what Polaris 2.0 refers to
  2. What 2.0 brings, according to the rc.1 changelog
  3. What release candidate means, and where Polaris 2.0's ended up
  4. How to test Polaris 2.0 in a branch
  5. Migrating components: Polaris React and what Polaris does not control
  6. Common mistakes
  7. Frequently asked questions
  8. Checklist

Polaris 2.0 is the new major version of Polaris web components, the library that embedded Shopify apps use to build their admin UI. The release candidate shipped on September 24, 2026, rc.1 followed on October 1, and since October 22 it has been stable: you load it from polaris-2.js.

Updated November 11, 2026: the release candidate is no longer the latest build. On October 22, Shopify released Polaris 2.0 as stable at polaris-2.js and polaris-2.0.js. The release candidate URL still responds, but it stopped at 2.0.0-rc.3. Below is what rc.1 changed, what that stage means, and how to test the stable release in a branch.

What Polaris is, and what Polaris 2.0 refers to

Polaris is Shopify's design system for the admin. For an embedded app's main interface, which Shopify calls App Home, Polaris today means web components: HTML elements with an s- prefix, such as <s-page>, <s-section> and <s-button>. A single script loaded from Shopify's CDN registers all of them, so there is nothing to import; you write them straight into your HTML or JSX. There is no npm package with the components. What npm carries is the TypeScript types, @shopify/polaris-types.

Polaris 2.0 is the second major version of that library: the polaris-2.js file on the CDN and @shopify/polaris-types 2.0.0. It is not a Polaris React release. The @shopify/polaris React package carries an npm notice that reads "Polaris React is deprecated and no longer maintained"; its last version is 13.9.5, from March 2025, and whatever it renders keeps the old look even on a page that loads Polaris 2.0.

The version number matters because, since August 31, 2026, the Polaris CDN follows semantic versioning. Major releases may contain breaking API or behavior changes, minor releases bring compatible components, fixes and visual refinements, and security fixes can land on older majors too. The types package shares the CDN's major version. The first minor under this model was Polaris 1.1, stable since September 22; 2.0 is the first major.

Why a major? The admin. Per the September 24, 2026 release candidate announcement, the new Shopify admin design began rolling out to merchants progressively on September 15. The Update your app for Polaris 2 guide explains the mechanism: the admin signals which styling to use through App Bridge, and Polaris 2.0 carries both styles and picks one at runtime. In a store with the new design, your components get the new color, typography, spacing and icons. In a store with the previous design, they look the same as with polaris-1.js. Polaris 1 does not contain the new styling at all, so an app that stays there keeps the current look in every store.

Two things that do not change: admin UI extensions and App Home UI extensions match each merchant's admin design on their own, with no code changes. And if your app is part of Built for Shopify, the announcement gives it until May 1, 2027 to make its App Home match the admin's visual style.

What 2.0 brings, according to the rc.1 changelog

On October 1, 2026, Shopify posted What's new in Polaris 2.0.0-rc.1. Its summary: more components aligned with the new admin style, fixes for several layout and event-handling bugs, and faster mounting and updates. The table lists every change in the entry and nothing else. The changelog names components in PascalCase (Table, Section); the table uses their tags, and each tag passed Shopify's Polaris validator.

ComponentChange in rc.1Changelog group
s-tableMatches the updated Shopify admin design.Components
s-tooltipCan be placed in the supplemental slot of s-section.Components
s-sectionEqual-height cards within the same s-grid.Components
s-selectMatches the height of s-text-field and other inputs.Components
s-badgePill shape on mobile.Components
s-bannerBetter title contrast.Components
s-color-pickerSaturation-well shadow fixed at the corners.Components
s-sectionOn narrow screens, the primary action moves below the card instead of squeezing the heading.Layout
s-sectionTighter spacing between headings and subheadings; headings in the aside use the default text color.Layout
s-menuIcons use the secondary icon color at rest.Layout
s-pageStyling of aside sections fixed.Layout
s-page and s-sectionSecondary actions no longer lose their disclosure icon when their menu or label is added after mount.Layout
Nested s-sectionThe first one no longer sits lower than other first children.Layout
Slotted actionsNo longer disappear when component markup is injected into an already-connected element.Layout
globalThis.polarisState is no longer lost when a page loads the bundle more than once.Reliability
s-modalActions fire a bubbling click even with commandFor set.Reliability
s-text-fieldAccessory clicks reach React onClick handlers.Reliability
PerformanceFaster mounting and updates, especially on pages without React, and less re-rendering from unrelated attribute changes on s-choice-list, s-menu, s-modal, s-select and pickers.Performance

The entry announces no new or removed components; every item adjusts a component that already existed. The real shift is in the September 24 announcement (both styles in one bundle) and in the look itself, which changes even when your code does not. npm also has an rc.2 (October 5) and an rc.3 (October 9) of the types, but we found no changelog entry of their own for either.

the components Polaris 2.0.0-rc.1 touches, per the changelogcomponentstylelayouteventsperformances-tables-sections-tooltips-selects-badges-banners-color-pickers-pages-menus-modals-text-fields-choice-listrc.1 is mostly visual: 8 of 12 componentsalso: equal-height cards in s-grid, fewer re-renders in pickers

Scroll the figure sideways to see all of it

What release candidate means, and where Polaris 2.0's ended up

In Semantic Versioning 2.0.0, a version with a hyphen after the number, like 2.0.0-rc.1, is a pre-release. The spec says it is unstable and might not satisfy the compatibility requirements of its normal version. The precedence example puts alpha before beta, beta before rc, and any rc before the plain version. In practice, release candidate means "this is what we plan to ship as stable, so test it."

Polaris skips alpha and beta. Per the semantic versioning entry, every change goes through a release candidate build first. That build is meant for development and testing, accumulates improvements during its window and updates in place at the same URL. The stable channels get the change after that phase. 2.0 followed exactly that path:

  • September 23 and 24: @shopify/polaris-types 2.0.0-rc.0 on npm, then the release candidate announcement with polaris-2.0-rc.js.
  • October 1: rc.1 and the changelog entry in the table above.
  • October 5 and 9: rc.2 and rc.3 of the types.
  • October 21 and 22: 2.0.0 on npm, then Polaris 2.0 stable on the CDN.
alpha, beta, release candidate, stable: the path Polaris 2.0 tooksemver precedence2.0.0-alphaunstable2.0.0-betaunstable2.0.0-rc.1candidate2.0.0stablePolaris shipped no alpha or beta of 2.0: only rc builds, then stablepolaris 2.0, release by releaserc.0Sep 23rc.1Oct 1rc.2Oct 5rc.3Oct 92.0.0Oct 22polaris-2.0-rc.js: same URL, moves with each rcpolaris-2.jsrelease candidate: ready to test, can still changerc dates: @shopify/polaris-types on npm · 2.0 stable on the CDN: Oct 22

Scroll the figure sideways to see all of it

The web components versioning docs make one detail explicit: promotion does not move the RC URL. The stable release gets its own URL, so switching to it is a change in your code. We checked on November 11 by downloading each file with curl and loading it offline in a local Chromium to read the version it reports.

ScriptServes today (Nov 11, 2026)Updates on its own?
polaris.js1.1.0Yes, within 1.x. It never moves to 2.x.
polaris-1.js1.1.0Yes, with each stable 1.x release.
polaris-2.0-rc.js2.0.0-rc.3Not anymore: promotion did not move it to stable.
polaris-2.js2.0.0Yes, with each stable 2.x release. The docs recommend this channel for production.
polaris-2.0.js2.0.0No: frozen, except for critical security fixes.
polaris-2.1-rc.jsDoes not exist (404)There is no 2.1 release candidate yet.

The types behave the same way, and this is where it is easiest to get it wrong. A normal npm range does not accept pre-releases:

$ npm view @shopify/polaris-types dist-tags
{ latest: '2.0.0', next: '2.0.0-rc.3' }
$ npm view "@shopify/polaris-types@^2.0.0" version
2.0.0
  1. dist-tags shows the package's two tags: latest points at the stable 2.0.0, and next stayed on the last RC.
  2. The ^2.0.0 range resolves to 2.0.0 only. rc.0 through rc.3 are left out, because npm excludes pre-releases from a normal range.
  3. To follow an RC, the docs say to use ^2.0.0-rc.0. We checked it with the semver module in npm 11.11.1: that range accepts 2.0.0-rc.3, 2.0.0 and 2.1.0, so pin the exact version if you want to stay on the RC.

How to test Polaris 2.0 in a branch

Now that 2.0 is stable, you test with polaris-2.js. The procedure is the one the announcement gave for the RC, and it carries over to the next one: when a 2.1 release candidate ships, swap the URL for polaris-2.1-rc.js and the types for ^2.1.0-rc.0. Work in a branch so production stays on Polaris 1 until you are done.

git switch -c polaris-2
npm install --save-dev @shopify/polaris-types@^2.0.0
shopify store create dev --name polaris-2-qa --feature-preview new_admin_design
shopify app dev
  1. git switch -c polaris-2 creates the branch. Everything below lives there until you merge.
  2. Installs the 2.0 types as a dev dependency. Per the docs, ^2.0.0 goes with polaris-2.js; if you pin polaris-2.0.js, use ~2.0.0.
  3. shopify store create dev creates a dev store, and --feature-preview new_admin_design turns on the "Shopify admin's new design" feature preview. You can only pick a preview when the store is created, and each store takes one. --name is required when the command runs non-interactively.
  4. shopify app dev runs your app against the store you choose. Repeat the test on a store without the preview to see the previous design.

We did not run the two shopify commands, since they need a Shopify login. Their syntax comes from the CLI docs.

Next, change the URL. An app built from the React Router template has no script tag of its own: AppProvider renders it, and the server configuration adds a Link header that preloads it. Change both places, to the same value:

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

// app/shopify.server.ts
const shopify = shopifyApp({
  // ...
  polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.js',
});
  1. polarisUrl on AppProvider decides which Polaris script the app renders.
  2. polarisUrl on shopifyApp decides which file the Link header preloads. If the two values differ, the browser preloads one bundle while the app loads another.
  3. Both options need @shopify/shopify-app-react-router 2.1.0 or later. Without them, versions 2.1.0 through 3.x default to polaris.js, which means Polaris 1. Per its changelog, 4.0.0, published October 21, switches the default to polaris-2.js.

If your app writes its own tag, change only the URL, and keep Polaris after App Bridge so App Bridge publishes the admin's signal before Polaris initializes:

<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>
  1. The meta tag tells App Bridge which app is loading.
  2. app-bridge.js is not versioned with Polaris: its URL has no number and always loads the latest App Bridge.
  3. polaris-2.js comes after it and is the only Polaris tag on the page. To test the RC, the announcement used polaris-2.0-rc.js here.

With the URL changed, build a test page with the components rc.1 touched and open it in both stores. This one passes Shopify's Polaris validator against types 1.0.1 and 2.0.0:

export function Polaris2Smoke() {
  return (
    <s-page heading="Polaris 2 smoke test">
      <s-button slot="primary-action" variant="primary">Save</s-button>
      <s-banner tone="info" heading="Polaris 2.0">
        Open this page in both admin designs.
      </s-banner>
      <s-grid gridTemplateColumns="1fr 1fr" gap="base">
        <s-section heading="Sync">
          <s-icon slot="supplemental" type="info" interestFor="sync-tip"></s-icon>
          <s-tooltip slot="supplemental" id="sync-tip">Runs every hour.</s-tooltip>
          <s-badge tone="success">Active</s-badge>
        </s-section>
        <s-section heading="Settings">
          <s-select label="Status" name="status">
            <s-option value="active">Active</s-option>
            <s-option value="draft">Draft</s-option>
          </s-select>
          <s-text-field label="Title" name="title"></s-text-field>
        </s-section>
      </s-grid>
      <s-section heading="Products" padding="none">
        <s-table>
          <s-table-header-row>
            <s-table-header listSlot="primary">Product</s-table-header>
            <s-table-header listSlot="inline">Status</s-table-header>
          </s-table-header-row>
          <s-table-body>
            <s-table-row>
              <s-table-cell>Cotton t-shirt</s-table-cell>
              <s-table-cell><s-badge tone="success">Active</s-badge></s-table-cell>
            </s-table-row>
          </s-table-body>
        </s-table>
      </s-section>
    </s-page>
  );
}
  1. s-page with an s-button in slot="primary-action": the primary action the admin coordinates with its title bar.
  2. s-banner with a heading: rc.1 improved that title's contrast.
  3. s-grid with two s-section elements of different length: since rc.1, cards in the same grid share one height.
  4. s-icon and s-tooltip in slot="supplemental": the tooltip can now sit in that slot, and interestFor ties the icon to it.
  5. s-badge: it turns into a pill on mobile.
  6. s-select next to s-text-field: they are now the same height.
  7. s-table inside an s-section with padding="none": the table in its updated design, edge to edge.

We rendered it offline in a local Chromium with copies of polaris-1.js, polaris-2.0-rc.js and polaris-2.js, at 900 and 375 pixels wide, with no console errors. Outside the admin, Polaris 2.0 defaults to the new style, and that is what we saw: with polaris-2.js the page title grew and the section headings moved out of the card. There is no App Bridge outside the admin either, so this check does not replace testing in the two stores.

To see which bundle your app actually loaded, open the browser console with your app's frame selected:

globalThis.polaris?.version
  1. In our test it returned '2.0.0' with polaris-2.js, '2.0.0-rc.3' with the RC URL and '1.1.0' with polaris.js or polaris-1.js. The property is not in the docs, so use it for debugging and never in app code. The documented check is the network panel, which should show a single request to a polaris-*.js file.

Migrating components: Polaris React and what Polaris does not control

Polaris 2.0 only changes what Polaris draws. Everything else stays as it is, and that is where the migration work lives: any Polaris React components you still have, and your own CSS.

If your app still uses Polaris React

Anything @shopify/polaris renders keeps the old look, so a page that mixes both systems ends up with two styles. The Polaris React migration guide suggests doing it in slices, one page or route family at a time, in this order: the page shell (Page, Card, Layout and page actions); display components (Badge, Banner, Text, Icon); buttons, links, menus, modals and popovers; forms; and finally tables, filters and bulk actions. The RC announcement agrees: start with Page, Section and Button, which have the largest visual effect. This is the guide's own example. Before:

import {Card, Page, Text} from '@shopify/polaris';

export function ProductsPage({onCreateProduct}) {
  return (
    <Page
      title="Products"
      primaryAction={{content: 'Create product', onAction: onCreateProduct}}
    >
      <Card>
        <Text as="h2" variant="headingSm">All products</Text>
        <Text as="p">Manage the products available through your app.</Text>
      </Card>
    </Page>
  );
}
  1. The component imports Card, Page and Text from @shopify/polaris, the deprecated package.
  2. Page takes the title and the primary action as React props.
  3. Card groups the content, and the heading is a Text with variant="headingSm".

After, with web components:

export function ProductsPage({onCreateProduct}) {
  return (
    <s-page heading="Products">
      <s-button
        slot="primary-action"
        variant="primary"
        onClick={onCreateProduct}
      >
        Create product
      </s-button>
      <s-section heading="All products">
        <s-paragraph>
          Manage the products available through your app.
        </s-paragraph>
      </s-section>
    </s-page>
  );
}
  1. No import: the CDN script registers the s- elements.
  2. title becomes heading on s-page.
  3. The primary action stops being an object and becomes an s-button with slot="primary-action" and variant="primary". There can only be one.
  4. There is no s-card: a card with a heading is an s-section with heading, and the text is an s-paragraph. This block passed the validator against types 1.0.1 and 2.0.0.

A few more rules from the guide that save time: multiword props are camelCase (accessibilityLabel, commandFor) while slot names stay kebab-case; url becomes href; modals, popovers and menus open through commandFor rather than controlled open state. .Polaris-* selectors cannot reach inside a web component, because the shadow DOM keeps them out. If you render the web components from React with controlled fields, you need React 19. And if your app sets a Content Security Policy, add https://cdn.shopify.com to script-src.

What Polaris does not control

The Polaris 2 guide asks you to check three things the library leaves alone. CSS that reads Polaris custom properties, or hardcodes values copied from @shopify/polaris-tokens, stays pinned to the old palette: replace it with your own tokens or with Polaris components. If your app hardcodes Inter, it keeps the old type; the new admin uses ShopifyInter, and Polaris 2.0 loads the right faces itself. And anything you hand-built to look like Polaris (cards, badges, banners, empty states) will look off next to the restyled components.

A fourth check does not depend on the Polaris version: the new admin floats UI over the bottom of your app, such as the Sidekick bar or mobile navigation. App Bridge reports that overlay's height as a CSS custom property and already pads the <body>, so this only matters if you position your own elements at the bottom:

.sticky-footer {
  position: fixed;
  bottom: var(--shopify-safe-area-inset-bottom, 0px);
}
  1. .sticky-footer is an example name: apply the rule to your own sticky footer or floating button.
  2. position: fixed is what you already had.
  3. bottom uses --shopify-safe-area-inset-bottom, the height App Bridge reports, with 0px as the fallback when nothing floats there. The Environment API documents it.
what you change in your app to move from Polaris 1 to Polaris 2.0wherepolaris 1polaris 2own <script>polaris-1.jspolaris-2.jsAppProvider polarisUrlpolaris.js (default)polaris-2.jsshopifyApp polarisUrlpolaris.js (default)the same value@shopify/polaris-types^1.1.0^2.0.0Polaris React@shopify/polariss-page · s-section · s-buttonfontsInter set in your CSSloaded by Polaris 2token-based CSS@shopify/polaris-tokensyour own tokenspolaris 2.0 does not arrive on its own: you switchfrom shopify-app-react-router 4.0.0 on, the default is polaris-2.js

Scroll the figure sideways to see all of it

Then walk your app's main flows in both stores, including empty states, error states and any screen that only appears after a long setup.

Common mistakes

  • Waiting for polaris.js to reach 2.0. It never will: the unversioned URL tracks 1.x for good. Moving to a new major is always explicit.
  • Staying on polaris-2.0-rc.js. Promotion did not move it, and it serves 2.0.0-rc.3 today. Switch to polaris-2.js, or to polaris-2.0.js if you want to pin.
  • Changing polarisUrl only on AppProvider. The Link header keeps preloading the other bundle. Change shopifyApp too.
  • Adding your own script tag to a template app. That makes two bundles, and the docs say it makes the app fail. In our test outside the admin there was no visible error and the second bundle won, so check the network panel: the problem may stay silent.
  • Bumping @shopify/shopify-app-react-router to 4.x without thinking about Polaris. If you never set polarisUrl, the app starts loading polaris-2.js and its look changes in that deploy. To stay on 1, its changelog says to set polaris-1.js in both places.
  • Using ^2.0.0 for the types while testing an RC. npm skips pre-releases. For an RC, use ^N.M.0-rc.0 or the exact version.
  • Testing only against the new design. During the progressive rollout, merchants are on both designs, and your app has to work on each.
  • Migrating half a page. When Polaris React and web components share a view, Polaris 2.0 shows two styles side by side.

Frequently asked questions

Is Polaris 2.0 still a release candidate?

No. The release candidate was announced on September 24, 2026, and the stable release shipped on October 22. The recommended URL today is polaris-2.js. The RC URL still responds, serving 2.0.0-rc.3, but it no longer gets changes.

Will my app change its look on its own?

Not while it loads polaris.js, polaris-1.js or a pinned 1.x release. There is one exception: on @shopify/shopify-app-react-router 4.0.0 or later with no polarisUrl set, the template loads polaris-2.js by default. Admin extensions, on the other hand, follow each store's design automatically.

Do I have to drop Polaris React to use Polaris 2.0?

Yes, for anything you want in the new style. Polaris 2.0 only changes the web components; whatever @shopify/polaris renders keeps the old look, and the package is marked deprecated on npm. Migrate page by page, starting with Page, Section and Button.

Is there a deadline to migrate?

For Built for Shopify apps, yes: May 1, 2027, for their App Home to match the admin's visual style. For everyone else, the sources we checked give no date. Polaris 1 stays available at polaris-1.js and, under the versioning model, can still receive security fixes.

Checklist

  • Your app uses Polaris web components, and whatever is left on @shopify/polaris is on a dated list.
  • You work in a branch, with production still on Polaris 1.
  • The URL is polaris-2.js (or a pinned polaris-2.0.js), not polaris-2.0-rc.js.
  • In template apps, polarisUrl has the same value on AppProvider and shopifyApp.
  • There is a single Polaris tag, after app-bridge.js, and the network panel shows a single request.
  • @shopify/polaris-types is on ^2.0.0, matching the URL.
  • You reviewed CSS built on Polaris tokens, hardcoded fonts and hand-built components.
  • Fixed-bottom elements use var(--shopify-safe-area-inset-bottom, 0px).
  • You walked the main flows in a store with new_admin_design and in one without it.

If your store also runs discounts on Shopify Scripts, the other migration on the list is moving Shopify Scripts to discount Functions. And if you are not sure your app needs an embedded interface at all, read what a Shopify custom app actually is: not every app does.

If your app also lives in checkout, see how to add a custom field with a checkout UI extension.

Saw this on Instagram? Comment POLARIS on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 11, 2026 · updated November 18, 2026

← Blog