What is Shopify Polaris?

Shopify Polaris: Polaris is Shopify's open-source React design system for building admin interfaces — a collection of accessible React components (DataTable, IndexTable, Card, ActionList, Modal, and 60+ others) paired with a design token system and interaction guidelines that make third-party app UIs look and behave like the native Shopify admin.; Also known as: @shopify/polaris, Polaris Design System, Shopify Design System

How It Works

Polaris is a standard npm package (@shopify/polaris) that you install in your React app. Wrap your app's root with <AppProvider> (imported from @shopify/shopify-app-remix/react in Remix apps, which combines Polaris and App Bridge providers) and import individual components as needed. Polaris components render HTML with CSS custom properties (design tokens) applied. The token system means that if Shopify updates the admin's visual language — border radii, spacing scale, color palette — your app inherits those changes automatically via a CSS variable update.

The component library is organized around layout primitives and content components. <Page> and <Layout> control page structure; <Card> (or the newer <BlockStack> / <InlineStack> primitives) handles surface grouping; <FormLayout> arranges form fields in the admin's standard grid; <IndexTable> builds sortable, filterable data tables with bulk actions — the same component that renders product, order, and customer lists in the Shopify admin itself. <DataTable> is the simpler table variant for read-only data. <ActionList> combined with <Popover> builds dropdown menus.

Polaris 12 (released 2024) is the current major version. It introduced the BlockStack and InlineStack layout primitives as replacements for the older <Stack> component. It also updated the design token naming convention to use a semantic scale (e.g., --p-space-400 instead of --p-space-4) and consolidated color tokens to use a role-based system (--p-color-bg-fill-brand instead of the hex-named variables from Polaris 10).

Why It Matters

Merchants spend hours in the Shopify admin every day. When a third-party app looks and behaves differently from the core admin — different button shapes, different spacing scale, different error message patterns — it creates cognitive friction. Polaris eliminates that friction by making your app's UI indistinguishable from the native admin. This isn't just an aesthetic benefit: Polaris components implement Shopify's established interaction patterns, so merchants already know how they work before they open your app.

Polaris also handles accessibility for you. Every interactive component ships with correct ARIA roles, keyboard navigation, focus management, and screen reader announcements. Building accessible form components and data tables from scratch is complex and time-consuming; using Polaris gives you WCAG 2.1 AA compliance by default. The Shopify App Store review process checks for accessibility issues, and non-compliant apps can be rejected.

The IndexTable component deserves special mention. Building a sortable, filterable data table with checkbox bulk selection, pagination, and keyboard navigation is one of the most labor-intensive UI tasks in any admin application. Polaris's <IndexTable> delivers this in ~50 lines of configuration. You supply the row data and column definitions; Polaris handles the rest — including the sticky header, responsive column hiding on mobile, and the bulk action toolbar that appears when rows are selected.

Polaris is used inside embedded apps (the <iframe> that loads your app in the Shopify admin). It is not used in checkout UI extensions or other non-admin extension surfaces — those use the @shopify/ui-extensions-react component library instead, which shares naming conventions with Polaris but runs in a sandboxed environment. Confusing these two is a common source of frustration: import { Button } from '@shopify/polaris' is for admin apps; import { Button } from '@shopify/ui-extensions-react' is for checkout extensions.

Compared to general-purpose design systems like Material UI or Radix UI, Polaris is narrower in scope (it's purpose-built for admin interfaces, not general web applications) but deeper in Shopify-specific patterns. If you're building an admin app, Polaris wins. If you're building a Hydrogen storefront, you'd use a different component library (Tailwind CSS with Headless UI is common) since you're building for end customers, not merchants.

Frequently asked questions

Is Polaris required for Shopify App Store listing?: Polaris is not technically required by Shopify's App Store review guidelines, but the guidelines do require that your app look and feel consistent with the Shopify admin, be accessible (WCAG 2.1 AA), and follow Shopify's UX patterns. In practice, building an admin app that passes review without Polaris means independently implementing all the same accessibility, interaction, and visual patterns — which is far more work. The vast majority of approved embedded apps use Polaris.
Can I mix Polaris with my own CSS or Tailwind?: Yes, but carefully. Polaris components are styled with CSS custom properties (design tokens). You can override tokens for app-specific branding in the `AppProvider` theme prop. Adding Tailwind on top of Polaris is possible but creates specificity conflicts — Tailwind's preflight reset can break Polaris base styles. A common pattern is to scope Tailwind utilities to specific non-Polaris sections of your app using Tailwind's `important` configuration or a custom layer.
How do I show a list of resources (like orders or products) with Polaris?: Use `<IndexTable>` for interactive lists with bulk actions, selection, and pagination — this is the correct component for order lists, product lists, or any resource list where merchants need to take action on multiple items. Use `<DataTable>` for read-only tabular data (analytics reports, inventory summaries). Use `<ResourceList>` (older, being phased out in favor of IndexTable) for simple lists without bulk selection. The Polaris documentation includes live examples and annotated code for each.

The Polaris documentation site (polaris.shopify.com) includes a full component gallery with live examples, design guidelines for each component, content writing guidelines, and a Figma component library for designers. For developers building their first admin app, the Remix app template scaffolded by shopify app generate includes Polaris pre-configured with the correct AppProvider setup and sample pages using <Page>, <Card>, and <BlockStack> as working starting points.

What is Shopify Polaris?