polaris-shadcn

shadcn/ui components styled with Shopify Polaris design tokens. Use the CLI to add components to your Vite + React project.

Getting started

polaris-shadcn requires Tailwind CSS v4 and a path alias (@/*).

1. Install Tailwind CSS v4

Skip this step if you already have Tailwind v4 set up.

npm install tailwindcss @tailwindcss/vite

Add the plugin to vite.config.ts:

import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

If you don't already have a CSS entrypoint, create app/app.css (or src/app.css) with the Tailwind v4 entrypoint import (@import "tailwindcss";), then import it in your root component (app/root.tsx for React Router apps):

// app/root.tsx
import "./app.css";

/* app/app.css */
@import "tailwindcss";

See the Tailwind CSS Vite guide for full details.

2. Configure path alias

The CLI requires an @/* import alias. Add to tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./app/*"]
    }
  }
}

And to vite.config.ts:

import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./app"),
    },
  },
});

Adjust ./app to ./src if your project uses a src/ directory.

3. Initialize polaris-shadcn

npx polaris-shadcn@latest init

This runs shadcn init using your project’s package manager (detected from packageManager in package.json or from your lockfile) and creates the theme file at app/styles/polaris-shadcn.css (or src/polaris-shadcn.css). It also strips shadcn’s color remapping in your Tailwind entry so bg-background uses the polaris-shadcn tokens. On fresh installs, it removes the shadcn/tailwind.css import and the default shadcn :root/.dark token blocks to avoid white backgrounds.

If your project doesn’t have a lockfile yet, pass --pm:

npx polaris-shadcn@latest init --pm pnpm

4. Import the theme

Add the import to your CSS entry point (app/app.css), after the Tailwind import:

@import "tailwindcss";
@import "./styles/polaris-shadcn.css";

5. Add components

npx polaris-shadcn@latest add button card tabs

Components are added to app/components/ui (or src/components/ui).

CLI options

# overwrite existing component files
npx polaris-shadcn@latest add button --force

# explicitly select the package manager for installs / fallback
npx polaris-shadcn@latest add button --pm pnpm

# custom components directory (should point to components/ui)
npx polaris-shadcn@latest add button --path app/components/ui

# custom theme file path
npx polaris-shadcn@latest add button --css app/styles/polaris-shadcn.css

# skip dependency installation
npx polaris-shadcn@latest add button --no-install

Fallback behavior

If a component isn’t in this repo’s registry, the CLI automatically falls back to:

pnpm dlx shadcn@latest add <component>
# yarn dlx shadcn@latest add <component>
# bunx shadcn@latest add <component>
# npx shadcn@latest add <component>

The fallback uses whatever shadcn configuration is present in your app and may prompt if components.json isn’t configured. Run npx polaris-shadcn@latest init (or npx shadcn@latest init) to set up that config first.

Demo app (this repo)

npm install
npm run dev

Vite will start the dev server (defaults to http://localhost:5173).

Screenshots

npm run screenshots

Runs the Playwright screenshot pipeline and writes images to ./screenshots/.

How it works

• src/components/ui/* contains the shadcn-style wrapper components used by the demo app.
• Polaris web components are loaded via the script tag in index.html.
• The demo theme layer lives in src/index.css.
• The CLI registry templates live in registry/templates and are copied into consuming apps.
• Demo routes are registered in src/demos/registry.jsx and rendered by src/pages/DemoPage.jsx.

Adding a new demo

1. Create or update a wrapper in src/components/ui/.
2. Add a new entry to demoRegistry in src/demos/registry.jsx with both the wrapper and Polaris-only demos.