Shopify Polaris for developers: building admin apps with web components

You find a Shopify Polaris tutorial, paste import {Page, Card} from '@shopify/polaris' into a new app and run npm install. npm answers with a warning: Polaris React is deprecated and no longer maintained.
Shopify Polaris itself is very much alive. It's Shopify's design system for app interfaces that look and behave like the Shopify admin: guidelines, design tokens, icons and a component library. Shopify's Polaris reference calls it "Shopify's unified UI framework built on web components." What's gone is the React library that most older tutorials teach.
This guide builds an embedded admin app UI the way Shopify documents it today. The steps come first. The component reference, accessibility rules, the Built for Shopify review and a fix-it table for migrations follow.
Polaris React or Polaris web components?
Use web components. Shopify released Polaris web components on October 1, 2025. The archived Polaris React repository says the React library "will not receive updates or maintenance." Its last npm release was 13.9.5, and the repository was archived on September 11, 2026.
| Polaris React | Polaris web components | |
|---|---|---|
| Package or source | @shopify/polaris on npm |
polaris-2.js from Shopify's CDN, plus @shopify/polaris-types for TypeScript |
| Status (October 2026) | Deprecated; last release 13.9.5 | Current; version 2.0 is the latest stable release |
| Framework | React only | Any framework or plain JavaScript |
| Syntax | <Page title="...">, <Card> |
<s-page heading="...">, <s-section> |
| Follows the new admin look | No; keeps the current appearance | Yes, with Polaris 2.0 |
| Docs | Archived docs | shopify.dev App Home reference |
The "new admin look" row is the one a product owner should read twice. Shopify is rolling out a new admin frame, navigation and visual appearance. Its Polaris 2 guide says any part of your UI still rendering @shopify/polaris React components keeps the old appearance. A half-migrated page will look out of place next to native admin screens.
Old bookmarks still work, sort of: polaris.shopify.com now redirects to the Polaris references page on shopify.dev.
Before you start
You need less than older guides suggest, because the CLI template ships the UI layer for you.
- Shopify CLI for scaffolding (
shopify app init) and local runs (shopify app dev). - A development store to run and test the app in.
@shopify/shopify-app-react-router2.1.0 or later if you want the CLI template on Polaris 2.- React 19 if you'll use controlled Polaris form fields from React. React 18 lacks the custom-element behavior they rely on.
@shopify/polaris-types@^2.0.0if you write TypeScript, so your types match the release you load.
Also check that Polaris is the right tool. It's for screens merchants use inside Shopify. A customer-facing storefront is a different build: a Liquid theme or a headless Hydrogen app, per Shopify's storefront docs.
How to build an admin app UI with Shopify Polaris
These steps follow Shopify's App Home documentation for the iframe model. You host the app yourself and use any framework, and Shopify recommends this model for most apps.
1. Scaffold the app
Run shopify app init and choose Build a React Router app when prompted. The template already includes the App Bridge and Polaris libraries, so there's no separate UI install.
2. Switch the template to Polaris 2
The template loads Polaris version 1 by default. To move to version 2, set polarisUrl in two places: the AppProvider in app/routes/app.tsx and your server config in app/shopify.server.ts.
If your app renders its own HTML head, Shopify's versioning reference gives this setup and recommends the polaris-2.js stable channel for production:
<!-- From Shopify's docs: App Bridge + Polaris web components -->
<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>
Load exactly one Polaris bundle, and load it after App Bridge.
3. Pick a page pattern before you write markup
Shopify publishes patterns: full-page templates for homepages, settings and resource pages, plus smaller compositions like data tables and setup guides. Start from the template closest to your screen. Shopify notes that patterns help apps meet Built for Shopify standards, and they save you from matching admin spacing by eye.
4. Build the App Home page
A minimal App Home page, as shown in Shopify's docs:
// From Shopify's App Home reference
export default function App() {
return (
<s-page heading="My App">
<s-section heading="Welcome">
<s-paragraph>
Welcome to your Shopify app! Start building the main interface here.
</s-paragraph>
</s-section>
</s-page>
);
}
In an embedded app, s-page hands its heading and actions to the admin title bar. For a primary action, put a single s-button with variant="primary" in the primary-action slot.
5. Add forms, with a label on every field
Settings and onboarding screens are mostly forms. Use the Polaris form components rather than raw inputs, since they collect input with validation built in. Shopify's accessibility example fits in four lines:
// From Shopify's web components guide
{/* Good - provides a label */}
<s-text-field label="Email address"></s-text-field>
{/* Bad - missing a label */}
<s-text-field></s-text-field>
For dialogs, use s-modal and put its action buttons in the component's slots. Built for Shopify reviewers look for that.
6. Put navigation and saving where merchants expect them
Use the App Bridge s-app-nav component for your app's main navigation and the contextual save bar for forms. Both are named items in the Built for Shopify design requirements. App Bridge components like these live in the admin chrome, outside your iframe.
7. Test in a dev store, in both admin appearances
Run shopify app dev to open the app in your development store with live reload. While the admin redesign rolls out, check every screen in a dev store with the new admin design feature preview and in one without it.
Shopify Polaris components by category
The App Home web components reference sorts the components into 7 categories. Forms is split in two below because it's the longest list.
| Category | Components |
|---|---|
| Actions | Button, Button group, Clickable, Clickable chip, Link, Menu |
| Feedback and status indicators | Badge, Banner, Empty state, Progress, Spinner |
| Forms: choices and pickers | Checkbox, Choice list, Color field, Color picker, Date field, Date picker, Drop zone, Select, Switch |
| Forms: text and data fields | Email field, Money field, Number field, Password field, Search field, Text area, Text field, URL field |
| Layout and structure | Box, Divider, Grid, Ordered list, Page, Query container, Section, Stack, Table, Unordered list |
| Media and visuals | Avatar, Icon, Image, Thumbnail |
| Overlays | Modal, Popover |
| Typography and content | Chip, Heading, Number, Paragraph, Text, Tooltip |
Notice what's missing. There's no card component, which trips up developers coming from React. You use s-section or a card pattern instead.
Polaris accessibility guidelines: what's built in and what's yours
Shopify's web components guide says the components "have accessibility built in." They use semantic HTML, support keyboard navigation, include ARIA attributes, manage focus and provide appropriate color contrast. They also log warnings when a required accessibility property is missing.
None of that covers the parts you assemble. Shopify leaves these to you:
- Set
labelanderroron every form field.labelAccessibilityVisibilityhides a label visually while keeping it for screen readers. - Use heading levels in order, with
s-headingor theheadingproperty. - Walk every flow with a keyboard only.
- Run Lighthouse, WAVE or Accessibility Insights, the tools Shopify's accessibility best practices recommend.
Shopify is careful about its own promise here. Its best practices page warns that following the guidance "doesn't guarantee that your app is completely accessible" by itself. For apps serving US merchants with ADA exposure, accessibility is something you test on every release, not something the library hands you.
What the Built for Shopify review checks
Built for Shopify is the App Store's quality badge, and meeting its design requirements "earns preferential treatment in the Shopify App Store," per Shopify's app design guidelines. The design section rests on three principles: apps should feel familiar, helpful and user-friendly.
The requirements page lists rejection reasons that read like a Polaris checklist:
- Most content doesn't sit in card-like containers similar to admin cards.
- Primary buttons use a color other than Polaris, such as green or purple.
- Body text size, background color or spacing differs significantly from the admin.
- Text fails WCAG 2.1 AA contrast.
- On mobile, a page scrolls horizontally or two-column layouts don't stack.
Design is only part of it. The app also needs at least 50 net installs from active shops on paid plans and at least 5 reviews. It must hit admin Web Vitals targets too: LCP of 2.5 seconds or less, CLS of 0.1 or less and INP of 200 milliseconds or less. Polaris clears most design rejections before review, but it won't speed up a slow backend.
Moving an existing Polaris React app across
You don't need a big-bang rewrite. Shopify's migration guide confirms both libraries can render in the same app while you migrate, so you can ship one route at a time.
Within each page, Shopify's order is the page shell first (Page, Card, Layout), then display components, then buttons and overlays, then forms. Tables and bulk actions move together as the last slice. Shopify also suggests installing its AI Toolkit for your coding agent and letting it migrate a route at a time. Someone still reviews each diff and tests it in a dev store before the next slice.
In practice, the first job is an inventory: which screens still render React components, and which ones use a component with no web component equivalent yet. As a Shopify Premier Partner, our Shopify development team would start an existing app there, before anyone touches code.
Troubleshooting Polaris web components
Most problems during a build or a migration trace back to one of these.
| What you see | Why | Fix |
|---|---|---|
| An error after adding the Polaris script | Two Polaris bundles are loaded | Load exactly one, after app-bridge.js |
| The app still runs Polaris 1 | The CLI template defaults to version 1 | Set polarisUrl in app/routes/app.tsx and app/shopify.server.ts |
| Controlled fields misbehave in React | React 18 lacks the custom-element behavior they need | Move to React 19 |
| Reading a field value through React props fails | Web components expose the value on the element | Read event.currentTarget.value |
| Custom CSS stopped applying | Shadow DOM blocks overrides that target .Polaris-* classes |
Remove the overrides; they can't reach inside the components |
| No card component | Polaris web components have no s-card |
Use s-section or a card pattern |
No replacement for Autocomplete |
Some React components have no direct equivalent yet | Leave that piece on Polaris React for now; both libraries can run together |
| Some screens keep the old admin look | Those screens still render @shopify/polaris React |
Migrate them to web components |
| Accessibility warnings in the console | A required accessibility property is missing | Add the property, usually label |
FAQ
Is Shopify Polaris open source?
The source is public, but the license isn't plain MIT. Shopify uses a custom license based on MIT that restricts Polaris to applications that integrate or interoperate with Shopify software or services. Standalone apps face extra restrictions and must be "dissimilar and visually distinct" from Shopify products, so Polaris isn't a general-purpose UI kit.
Where else does Polaris appear besides App Home?
Every Shopify app surface uses Polaris web components. That includes admin UI extensions on product, order and customer pages, checkout and customer account extensions, and POS extensions on the smart grid, cart and post-purchase screens. Each surface has its own extension APIs and allows only its own subset of components.
Do I have to host my app to use Polaris?
Not necessarily. Shopify also offers a UI extension model for App Home that avoids hosting. The trade-offs are real: you're limited to Preact, a 64 KB compressed bundle and custom distribution only. That's why Shopify recommends the self-hosted iframe model for most apps.
