polaris
Shopify’s design system to help us work together to build a great experience for all of our merchants.
Top Related Projects
The CSS design system that powers GitHub
An enterprise-class UI design language and React UI library
Material UI: Comprehensive React component library that implements Google's Material Design. Free forever.
A utility-first CSS framework for rapid UI development.
BootstrapVue provides one of the most comprehensive implementations of Bootstrap v4 for Vue.js. With extensive and automated WAI-ARIA accessibility markup.
🐉 Vue Component Framework
Quick Overview
Shopify/polaris is an open-source design system and React component library developed by Shopify. It provides a comprehensive set of reusable UI components, design guidelines, and tools to help developers and designers create consistent, high-quality user interfaces for Shopify applications and other web projects.
Pros
- Comprehensive set of well-designed, accessible React components
- Consistent design language and guidelines for Shopify-like interfaces
- Regular updates and maintenance by Shopify's team
- Extensive documentation and examples
Cons
- Primarily designed for Shopify ecosystem, may require customization for other use cases
- Learning curve for developers unfamiliar with Shopify's design patterns
- Some components may be overly opinionated or complex for simpler projects
- Dependency on React framework limits usage in non-React projects
Code Examples
- Using a basic Button component:
import {Button} from '@shopify/polaris';
function MyComponent() {
return <Button onClick={() => console.log('Button clicked')}>Click me</Button>;
}
- Creating a form with TextField and Select components:
import {Form, FormLayout, TextField, Select} from '@shopify/polaris';
function MyForm() {
return (
<Form onSubmit={handleSubmit}>
<FormLayout>
<TextField label="Name" onChange={handleNameChange} />
<Select
label="Category"
options={[
{label: 'Option 1', value: '1'},
{label: 'Option 2', value: '2'},
]}
onChange={handleCategoryChange}
/>
</FormLayout>
</Form>
);
}
- Using the Page component with a title and actions:
import {Page, Button} from '@shopify/polaris';
function MyPage() {
return (
<Page
title="Products"
primaryAction={<Button primary>Add product</Button>}
secondaryActions={[
{
content: 'Export',
onAction: handleExport,
},
]}
>
{/* Page content goes here */}
</Page>
);
}
Getting Started
To start using Polaris in your React project:
- Install the package:
npm install @shopify/polaris
- Import and set up the AppProvider component in your app's root:
import {AppProvider} from '@shopify/polaris';
import '@shopify/polaris/build/esm/styles.css';
function App() {
return (
<AppProvider i18n={{}}>
{/* Your app components */}
</AppProvider>
);
}
- Start using Polaris components in your React components:
import {Card, Button} from '@shopify/polaris';
function MyComponent() {
return (
<Card title="Getting Started">
<Card.Section>
<p>Welcome to Polaris!</p>
<Button primary>Get started</Button>
</Card.Section>
</Card>
);
}
Competitor Comparisons
The CSS design system that powers GitHub
Pros of primer/css
- More flexible and adaptable for various projects beyond e-commerce
- Larger community and wider adoption across different types of applications
- More comprehensive documentation and examples
Cons of primer/css
- Less specialized for e-commerce specific needs
- May require more customization for complex e-commerce interfaces
- Lacks some advanced components that Polaris provides out-of-the-box
Code Comparison
primer/css:
.btn {
display: inline-block;
padding: 6px 12px;
font-size: 14px;
font-weight: 600;
line-height: 20px;
white-space: nowrap;
vertical-align: middle;
cursor: pointer;
user-select: none;
background-repeat: repeat-x;
background-position: -1px -1px;
background-size: 110% 110%;
border: 1px solid rgba(27,31,35,.2);
border-radius: .25em;
appearance: none;
}
Polaris:
.Button {
position: relative;
display: inline-flex;
align-items: center;
justify-content: center;
min-height: 3.6rem;
min-width: 3.6rem;
margin: 0;
padding: 0.7rem 1.6rem;
background: linear-gradient(to bottom, #ffffff, #f9fafb);
border: .1rem solid #c4cdd5;
box-shadow: 0 1px 0 0 rgba(22, 29, 37, 0.05);
border-radius: 3px;
line-height: 1;
color: #212b36;
text-align: center;
cursor: pointer;
user-select: none;
text-decoration: none;
transition-property: background, border, box-shadow;
transition-duration: 200ms;
transition-timing-function: cubic-bezier(0.64, 0, 0.35, 1);
}
An enterprise-class UI design language and React UI library
Pros of Ant Design
- Larger ecosystem with more components and tools
- Extensive documentation and examples
- Strong community support and frequent updates
Cons of Ant Design
- Steeper learning curve due to its comprehensive nature
- Larger bundle size, which may impact performance
- Less opinionated design, requiring more customization effort
Code Comparison
Ant Design button example:
import { Button } from 'antd';
const MyComponent = () => (
<Button type="primary">Click me</Button>
);
Polaris button example:
import { Button } from '@shopify/polaris';
const MyComponent = () => (
<Button primary>Click me</Button>
);
Both Ant Design and Polaris are popular React UI component libraries, but they cater to different needs. Ant Design offers a more extensive set of components and is widely used in various industries, while Polaris is specifically tailored for Shopify's ecosystem and design language.
Ant Design provides more flexibility and customization options, making it suitable for a broader range of projects. However, this flexibility comes at the cost of a steeper learning curve and potentially larger bundle sizes.
Polaris, on the other hand, offers a more streamlined and opinionated approach, which can lead to faster development times for Shopify-related projects. It has a smaller footprint and is easier to get started with, but may be less suitable for non-Shopify applications.
Material UI: Comprehensive React component library that implements Google's Material Design. Free forever.
Pros of Material-UI
- Larger ecosystem with more components and third-party extensions
- More flexible theming system, allowing for deeper customization
- Better support for server-side rendering and static site generation
Cons of Material-UI
- Steeper learning curve due to more complex API and configuration options
- Larger bundle size, which may impact initial load times
- Less opinionated design, requiring more effort to achieve a cohesive look
Code Comparison
Material-UI:
import { Button, ThemeProvider, createTheme } from '@mui/material';
const theme = createTheme({
palette: { primary: { main: '#1976d2' } },
});
<ThemeProvider theme={theme}>
<Button variant="contained" color="primary">Click me</Button>
</ThemeProvider>
Polaris:
import { Button, AppProvider } from '@shopify/polaris';
<AppProvider i18n={{}}>
<Button primary>Click me</Button>
</AppProvider>
Material-UI offers more granular control over theming and component variants, while Polaris provides a simpler API with predefined styles adhering to Shopify's design system. Material-UI's approach requires more setup but offers greater flexibility, whereas Polaris focuses on consistency and ease of use within the Shopify ecosystem.
A utility-first CSS framework for rapid UI development.
Pros of Tailwind CSS
- Highly customizable and flexible, allowing for rapid UI development
- Utility-first approach enables quick styling without leaving HTML
- Large and active community, with extensive documentation and resources
Cons of Tailwind CSS
- Steeper learning curve for developers new to utility-first CSS
- Can lead to longer class strings in HTML, potentially reducing readability
- Requires additional configuration for optimal performance in production
Code Comparison
Tailwind CSS:
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
Click me
</button>
Polaris:
import {Button} from '@shopify/polaris';
<Button primary>Click me</Button>
Summary
Tailwind CSS offers greater flexibility and customization, while Polaris provides a more opinionated, component-based approach. Tailwind's utility-first methodology allows for rapid development but may result in longer class strings. Polaris offers a cohesive design system with pre-built components, making it easier to maintain consistency across Shopify-based projects. The choice between the two depends on project requirements, team preferences, and the desired level of customization.
BootstrapVue provides one of the most comprehensive implementations of Bootstrap v4 for Vue.js. With extensive and automated WAI-ARIA accessibility markup.
Pros of Bootstrap Vue
- Larger ecosystem and community support
- More comprehensive set of UI components
- Easier integration with existing Bootstrap projects
Cons of Bootstrap Vue
- Heavier bundle size due to Bootstrap dependency
- Less opinionated design system, requiring more customization
- Steeper learning curve for developers new to Bootstrap
Code Comparison
Bootstrap Vue component usage:
<template>
<b-button variant="primary" @click="handleClick">
Click me
</b-button>
</template>
Polaris component usage:
import {Button} from '@shopify/polaris';
function MyComponent() {
return <Button onClick={handleClick}>Click me</Button>;
}
Both libraries offer component-based approaches, but Polaris uses a more React-centric syntax, while Bootstrap Vue follows Vue.js conventions. Polaris components are generally more streamlined and require fewer props for basic usage, whereas Bootstrap Vue components often offer more customization options out of the box.
🐉 Vue Component Framework
Pros of Vuetify
- Larger ecosystem with more components and pre-built layouts
- Better documentation and extensive examples
- More flexible theming system with built-in material design support
Cons of Vuetify
- Steeper learning curve due to more complex API
- Larger bundle size, which may impact performance
- Less opinionated, requiring more decision-making from developers
Code Comparison
Vuetify component usage:
<template>
<v-app>
<v-btn color="primary">Click me</v-btn>
</v-app>
</template>
Polaris component usage:
import { Page, Button } from '@shopify/polaris';
function MyComponent() {
return (
<Page>
<Button primary>Click me</Button>
</Page>
);
}
Both Vuetify and Polaris offer comprehensive UI component libraries, but they cater to different needs. Vuetify is more feature-rich and flexible, making it suitable for a wide range of projects. Polaris, on the other hand, is tailored specifically for Shopify-related applications, providing a more focused and opinionated approach.
Vuetify's extensive documentation and examples make it easier for developers to get started, but the larger API can be overwhelming. Polaris offers a simpler API, which can lead to faster development for Shopify-specific projects.
Ultimately, the choice between Vuetify and Polaris depends on the project requirements, target platform, and developer preferences.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Polaris
Build. Contribute. Evolve. Shape the merchant experience for Shopifyâs core product, the admin.
Status | Owner | Help |
---|---|---|
Active | @shopify/polaris | New issue |
About this repo
The shopify/polaris repository is an intergalactic monorepo made up of NPM packages, VSCode extensions, and websites.
polaris/
âââ documentation # Documentation for working in the monorepo
âââ polaris-for-vscode # VS Code extension for Polaris
âââ polaris-icons # Icons for Polaris
âââ polaris-react # Components for @shopify/polaris package
âââ polaris-tokens # Design tokens for Polaris
âââ polaris.shopify.com # Documentation website
âââ stylelint-polaris # Rules for custom property usage and mainline coverage
Commands
Install dependencies and build workspaces
pnpm install && pnpm build
Run a command
One workspace
Run commands from a selected workspace using turbo run <command> --filter=<workspace>...
flag.
Command | Runs |
---|---|
pnpm turbo run dev --filter=@shopify/polaris | Open the react component storybook |
pnpm turbo run dev --filter=polaris.shopify.com | Open polaris.shopify.com NextJS site |
All workspaces
Run commands across all workspaces. This uses turbo run <command>
.
Command | Runs |
---|---|
pnpm changeset | Adds a new changelog entry |
pnpm lint | Lints all workspaces |
pnpm test | Tests all workspaces |
pnpm type-check | Build types and check for type errors |
pnpm clean | Remove generated files |
pnpm format | Format files with prettier |
Contribute to this repo
Pull requests are welcome. See the contribution guidelines for more information.
Licenses
Source code is under a custom license based on MIT. The license restricts Polaris usage to applications that integrate or interoperate with Shopify software or services, with additional restrictions for external, stand-alone applications.
All icons and images are licensed under the Polaris Design Guidelines License Agreement
Top Related Projects
The CSS design system that powers GitHub
An enterprise-class UI design language and React UI library
Material UI: Comprehensive React component library that implements Google's Material Design. Free forever.
A utility-first CSS framework for rapid UI development.
BootstrapVue provides one of the most comprehensive implementations of Bootstrap v4 for Vue.js. With extensive and automated WAI-ARIA accessibility markup.
🐉 Vue Component Framework
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot