Shopify’s product component library
TypeScript CSS JavaScript Other
Latest commit 07584dd Jul 13, 2018
Permalink
Failed to load latest commit information.
.circleci v2.4.0 Jul 13, 2018
.github v2.4.0 Jul 13, 2018
.vscode v2.2.0 Jun 12, 2018
config v2.3.0 Jul 3, 2018
documentation v2.4.0 Jul 13, 2018
examples v2.4.0 Jul 13, 2018
playground v2.3.0 Jul 3, 2018
scripts v2.3.0 Jul 3, 2018
shrink-ray-build v2.0.0-beta.18 Apr 20, 2018
src v2.4.0 Jul 13, 2018
tests v2.3.0 Jul 3, 2018
visual-regression-testing-build v2.4.0 Jul 13, 2018
.babelrc v1.0.3 May 11, 2017
.editorconfig v2.2.0 Jun 12, 2018
.eslintignore v2.1.0 May 30, 2018
.eslintrc v2.1.0 May 30, 2018
.gitignore v2.3.1 Jul 5, 2018
.nvmrc v2.1.2 Jun 6, 2018
.prettierignore v2.1.0 May 30, 2018
.prettierrc v2.1.0 May 30, 2018
.yarnclean v1.8.1 Oct 24, 2017
CHANGELOG.md v2.4.0 Jul 13, 2018
LICENSE.md v2.0.0-beta.8 Mar 1, 2018
README.md v2.4.0 Jul 13, 2018
app.json v2.1.0 May 30, 2018
dev.yml v2.4.0 Jul 13, 2018
package.json v2.4.0 Jul 13, 2018
pre-commit v1.4.0 Aug 23, 2017
shipit.yml v2.3.1 Jul 5, 2018
tsconfig.json v2.2.0 Jun 12, 2018
yarn.lock v2.4.0 Jul 13, 2018

README.md

Polaris

CircleCI

Polaris is a React component library designed to help developers create the best experience for merchants who use Shopify. Visit the Polaris style guide to learn more.

Using the React components

We strongly recommend using the React versions of our components. It’s the version that we’ll be using internally. It allows for rich, complex components like Tabs and Popovers, and will not have as many breaking changes as the CSS-only version.

Installation:

Run the following command using npm:

npm install @shopify/polaris --save

If you prefer Yarn, use the following command instead:

yarn add @shopify/polaris

Usage

  1. Include the CSS in your HTML:
 <link rel="stylesheet" href="https://sdks.shopifycdn.com/polaris/2.4.0/polaris.min.css" />

Note: you can import the CSS directly into your project if your asset packager supports it:

import '@shopify/polaris/styles.css';
  1. Include any of the provided components in your project:
import {AppProvider, Page, Card, Button} from '@shopify/polaris';
  1. Tell React to render the element in the DOM:
ReactDOM.render(
  <AppProvider>
    <Page title="Example app">
      <Card sectioned>
        <Button onClick={() => alert('Button clicked!')}>Example button</Button>
      </Card>
    </Page>
  </AppProvider>,
  document.querySelector('#app'),
);

Using the Embedded App SDK

We provide React wrappers around Shopify’s Embedded App SDK (EASDK). You don’t need to go through the initialization of the EASDK as described in the docs. Instead, configure the connection to the Admin through the AppProvider component.

Using the CSS components

If React doesn’t make sense for your application, you can use a CSS-only version of our components. This includes all the styles you need for every component in the library, but you’ll be responsible for writing the correct markup and updating classes and DOM attributes in response to user events.

Usage

  1. Include the CSS in your HTML:
<link rel="stylesheet" href="https://sdks.shopifycdn.com/polaris/2.4.0/polaris.min.css" />
  1. Include the markup and associated classes in your HTML document:
<button class="Polaris-Button">Example button</button>

Examples

We have created example applications to document some of the ways you could include Polaris in one of your own applications. Each of these examples includes further documentation on how to install dependencies and run the app:

We’ve also created a simple, hot-reloading playground for these components. You can edit the playground/Playground.tsx file to import the components you want to play with, and run yarn dev in order to start the development server.

Learning resources

If you’re new to React, we recommend you start with the official React Getting Started documentation. As you read through the topics we suggest you follow along using their React Hello World CodePen example.

Additional resources:

Methodology

We set out to make our components easy to use. Each of our components has a well-documented (and fully typed) public interface with strong, consistently-applied conventions. This way, developers don’t need to worry about the underlying implementation. Instead, they can focus on creating amazing merchant experiences.

We ensure that our components are made for everyone. They meet accessibility standards and are responsive to any screen or device. We also put a lot of effort into optimizing the performance of the components, so everyone can build inclusive experiences that work.

We make our components flexible enough to meet diverse needs. They present the information you pass in and give you smart callbacks when something has changed, but they don’t enforce any structure beyond that. No matter what type of experience you’re creating, you can use components as the building blocks of your product or feature.

Contributing

We’re working on making this project fully open source. We aren’t accepting pull requests, but issue reports and feature requests are welcome. See the contribution guidelines for more information.

Licenses