Skip to content

What Is Shopify Polaris?

Definition

Polaris is Shopify's design system for apps: the components, styles and guidelines that make an app look and behave like the Shopify admin. It now ships as Polaris web components, used in App Home and in admin, checkout, customer account and POS extensions. The older Polaris React library is deprecated and no longer maintained.

How Polaris works

Polaris is the design system behind Shopify apps: a set of UI components, styles and guidelines that make an app look and behave like the Shopify admin it lives in. Shopify describes it as its "unified UI framework built on web components", and every app surface uses it to keep the experience consistent.[1]

The surfaces are App Home, which is the app's main page inside the admin, plus admin UI extensions, checkout UI extensions, customer account UI extensions and POS UI extensions. Each surface gets its own subset of Polaris web components.[1] The components are native UI elements built with remote-dom, Shopify's library for cross-platform interfaces, and they come with accessibility built in: semantic HTML, keyboard navigation, ARIA attributes, focus management and appropriate colour contrast.[2]

In App Home, an app renders inside an iframe and talks to the rest of the admin through App Bridge, a JavaScript SDK. Polaris supplies the components; App Bridge connects the app to the admin.[3] In practice a developer adds two script tags to the app's HTML head, one for App Bridge and one for Polaris, and builds pages from elements such as s-page, s-section and s-button.[3][4] Because they follow the Web Components standard, the components work in any framework or with plain JavaScript, like a native button or input.[3] The old documentation site at polaris.shopify.com now forwards to these references on shopify.dev.

Polaris versions: React, web components and Polaris 2

"Polaris" has meant different code over the years, which is why two developers can quote very different work for the same app:

VersionStatusWhat it means for an app
Polaris React (@shopify/polaris)Deprecated. The repository is archived and "will not receive updates or maintenance".[5]Existing apps keep working, but parts of a UI built with it keep the current admin appearance.[6]
Polaris web componentsReleased October 1, 2025; Shopify encourages them for all new development.[5]Framework-agnostic: React, Vue, server-rendered pages or plain JavaScript.[3]
Polaris 2.0 for App HomeThe version the current App Home reference documents.[3]Matches the updated Shopify admin, with its new frame, navigation and visual appearance.[6]

Polaris 2.0 changes how components look, not how you use them. It has the same components, properties and events as Polaris 1.1, so markup that works on 1.1 works on 2.0. An app built entirely with Polaris web components adopts the new admin styling just by loading 2.0, while an app on Polaris 1, or any part of a UI that still renders Polaris React, keeps the current appearance.[6] The library is versioned, and Shopify recommends loading the stable channel for your major version, which always serves the newest stable release.[4]

App Home can be built two ways. The iframe model works with any framework, is hosted by you and suits both public and custom apps. An App Home UI extension is hosted by Shopify, runs on Preact, has a 64 KB compressed bundle limit, may use only Polaris web components and is limited to custom distribution.[7]

Polaris and Built for Shopify

For App Store apps, looking native is a written requirement. Built for Shopify criterion 4.1 says an app "generally looks and behaves like the Shopify admin", and that its UI "should mimic Shopify's core look and feel".[8] The listed reasons for rejection read like a Polaris checklist:[8]

  • Primary buttons in a completely different colour than Polaris, such as green or purple.
  • A serif or script font for most of the content, or body text much larger or smaller than the admin's.
  • A background colour very different from the admin's, such as black.
  • Most content outside card-like containers that resemble admin cards.
  • Text that fails WCAG 2.1 AA contrast.
  • A modal built with the deprecated Polaris Fullscreen bar component instead of the current App Bridge window and page components.

Shopify's App Design Guidelines go one step further and recommend Polaris components for all apps embedded in the admin, with the argument that "by using Polaris, your app can evolve with us".[9] Colour is where apps most often drift. Shopify's rule is that colour roles show the state of something, such as an unfulfilled order or a failed sync, and must never be used to tell categories apart.[10] Our breakdown of Polaris colour tokens, hex values and tones shows how those roles map to real values.

Example: a custom wholesale price list app

Take a hypothetical store with four staff who manage wholesale price lists every day. It commissions a custom app with six screens: list, editor, CSV import, import log, settings and help. Two ways to build it:

  • Built with Polaris web components in App Home. The title bar and the navigation come from App Bridge, unsaved changes use the admin's contextual save bar, and the screens are made of Polaris cards, tables and badges.[3][8] When the admin moves to its new appearance, the update is loading Polaris 2.0 and checking the few parts Polaris doesn't control.[6]
  • Built with a custom React UI in brand colours. Green primary buttons, a black header and the app's own menu. Staff now switch between two interface languages many times a day, and every admin redesign means restyling all six screens by hand. If the app is ever offered on the App Store, Built for Shopify rejects both the off-Polaris button colour and an app menu that replaces the admin navigation.[8]

The second option often looks better in a pitch deck. The first is what the four people using it every day will thank you for, and it is cheaper to keep alive.

Polaris vs App Bridge

PolarisApp Bridge
What it isDesign system and UI components[1]JavaScript SDK that connects an app to the Shopify admin[3]
Gives youButtons, cards, forms, tables, badges and other page contentTitle bar, admin navigation, save bar and app windows around your app[9][8]
Where it runsApp Home and admin, checkout, customer account and POS extensions[1]Embedded apps in the Shopify admin[3]
VersioningVersioned library, currently Polaris 2.0[4]Separate; the Polaris version does not change App Bridge elements[6]

FAQ

Is Polaris React deprecated?

Yes. Shopify's repository says the Polaris React library is deprecated, archived and will not receive updates or maintenance. Shopify encourages Polaris web components, released October 1, 2025, for new development.[5]

Do checkout extensions use Polaris?

Yes. Checkout UI extensions, like admin, customer account and POS extensions, render with Polaris web components. Each surface has its own subset of components.[1]

Does a custom app have to use Polaris?

Built for Shopify applies to App Store apps, so a custom app is not reviewed against it. Shopify still recommends Polaris for every embedded app, and an App Home UI extension can use only Polaris web components.[7][9]

What is Polaris 2?

Polaris 2.0 is the version of Polaris web components for App Home that matches the updated Shopify admin appearance. It keeps the same components and properties as Polaris 1.1.[6]

Can I use Polaris without React?

Yes. Polaris web components follow the Web Components standard, so they work with any framework or with plain JavaScript.[3]

The bottom line

Polaris is Shopify's design system for apps, and today it means Polaris web components across App Home and every extension surface. Polaris React is deprecated, and Polaris 2.0 is what keeps an app in step with the new admin. For an app on the App Store, a native look is a Built for Shopify requirement; for a custom app, it is simply what makes staff faster. Our custom Shopify app team builds on Polaris web components by default, and our post on Shopify App Store guidelines covers the review that public apps face.

Article sources

We use primary sources only: official documentation, product pages and laws. Each link was checked on the date shown.

  1. Shopify Dev. Polaris references. Accessed 18th Nov 2026.
  2. Shopify Dev. Using web components. Accessed 18th Nov 2026.
  3. Shopify Dev. App Home iframe apps. Accessed 18th Nov 2026.
  4. Shopify Dev. Versioning for web components. Accessed 18th Nov 2026.
  5. Shopify on GitHub. Polaris React (archived repository). Accessed 18th Nov 2026.
  6. Shopify Dev. Update your app for Polaris 2. Accessed 18th Nov 2026.
  7. Shopify Dev. Apps in App Home. Accessed 18th Nov 2026.
  8. Shopify Dev. Built for Shopify requirements. Accessed 18th Nov 2026.
  9. Shopify Dev. App Design Guidelines. Accessed 18th Nov 2026.
  10. Shopify Dev. Visual design. Accessed 18th Nov 2026.

Need this on your store?

See the service

The checklist we run before touching a client's code

Get it by email, plus a few short notes over the next two weeks: what we see most often on Shopify stores and what actually fixes it.

No spam. Unsubscribe anytime. Privacy Policy