Skip to content
Shopify’s product component library
TypeScript CSS JavaScript Other
Branch: master
Clone or download
Latest commit f4ab0c8 Jan 27, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.github Update discoverability.yml Jan 25, 2020
.shopify-build Re-enable consumer build web unit tests (#2663) Jan 25, 2020
.storybook
.vscode Recommend official stylelint extension (#2595) Jan 6, 2020
config convert colors to HSLuv Nov 5, 2019
documentation
examples Bump handlebars from 4.1.2 to 4.5.3 in /examples/create-react-app Jan 6, 2020
locales Update locales/nl.json (#2673) Jan 28, 2020
playground [Frame] Apply design language to TopBar and Navigation (#2602) Jan 20, 2020
scripts Stop package.json being included in esnext folder (#2668) Jan 27, 2020
src v4.12.0 Jan 28, 2020
tests Update component indexes to use export * Jan 17, 2020
.editorconfig Allow trailing whitespace in diff and markdown files (#1499) Jun 7, 2018
.eslintignore Fixed position overlay positioning (#2231) Oct 16, 2019
.eslintrc [Color system] nested ThemeProvider (#2459) Dec 13, 2019
.gitattributes Union merge conflicting changes (accept both) in UNRELEASED.md (#2436) Nov 15, 2019
.gitignore Add minified styles to npm package (#1957) Aug 13, 2019
.nvmrc Update to use node v10.13.0 Nov 5, 2018
.prettierignore Add minified styles to npm package (#1957) Aug 13, 2019
.prettierrc Stop prettier rampaging over markdown files May 28, 2018
.stylelintignore Add minified styles to npm package (#1957) Aug 13, 2019
.yarnclean Upgrade to React 16 Oct 19, 2017
CHANGELOG.md Prepare changelog for v4.12.0 Jan 28, 2020
LICENSE.md Update license (#2489) Oct 24, 2018
README.md v4.12.0 Jan 28, 2020
UNRELEASED.md Prepare changelog for v4.12.0 Jan 28, 2020
app.json [yarn tophat] Fix app loading issues on Heroku (#2027) Aug 27, 2018
babel.config.js Storybook: Make babel read ts files instead of using ts-loader Jun 19, 2019
codecov.yml increase code coverage check minimum to 90% Feb 21, 2019
dev.yml add `dev test:coverage`, `dev open coverage`, and `yarn open:coverage` Dec 4, 2019
package.json v4.12.0 Jan 28, 2020
prImpactData.json Splash add impact size data (#2649) Jan 23, 2020
pre-commit add override docs, move overrides to tokens file (#2515) Dec 5, 2019
secrets.ejson Use unpkg for CDN links for CSS files (#1960) Aug 19, 2019
service.yml Update service.yml Nov 20, 2019
sewing-kit.config.ts Dependency updates (#2326) Oct 18, 2019
shipit.yml hide github automations from shipit Jun 26, 2019
translation.yml [i18n] Add new beta and future supported languages Oct 3, 2019
tsconfig.json Enable strictPropertyInitialization TS config (#2553) Dec 18, 2019
yarn.lock Splash add impact size data (#2649) Jan 23, 2020

README.md

Polaris React

npm version CircleCI build status codecov PRs Welcome

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

App development

For more information about creating apps for the Shopify App Store, take a look at the app development documentation.

Using the React components

While we do offer a CSS-only version, we strongly recommend using the React versions of our components. It’s the version that we use at Shopify. 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. Import the CSS directly into your project if your asset packager supports it:
import '@shopify/polaris/styles.css';

Otherwise include the CSS in your HTML. We suggest copying the styles file into your own project, but you may also use it directly:

<link
  rel="stylesheet"
  href="https://unpkg.com/@shopify/polaris@4.12.0/styles.min.css"
/>
  1. Include the translations and any of the provided components in your project:
import enTranslations from '@shopify/polaris/locales/en.json';
import {AppProvider, Page, Card, Button} from '@shopify/polaris';
  1. Tell React to render the element in the DOM:
ReactDOM.render(
  <AppProvider i18n={enTranslations}>
    <Page title="Example app">
      <Card sectioned>
        <Button onClick={() => alert('Button clicked!')}>Example button</Button>
      </Card>
    </Page>
  </AppProvider>,
  document.querySelector('#app'),
);

Building an embedded app

We provide React wrappers around the Shopify App Bridge (formerly known as the EASDK). You don’t need to go through the initialization of the Shopify App Bridge as described in the docs. Instead, configure the connection to the Shopify admin through the app provider component.

If you need help using Shopify App Bridge, the Embedded App SDK, or the POS App SDK, please visit our API & SDK forum. It is the best place to discuss the libraries, get support, notify us about bugs, or request features.

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. We suggest copying the styles file into your own project, but you may also use it directly:
<link
  rel="stylesheet"
  href="https://unpkg.com/@shopify/polaris@4.12.0/styles.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:

Development

We use Storybook to create a simple, hot-reloading playground for development on these components. You can edit the playground/Playground.tsx file to import the components you are working on, and run yarn dev in order to start the development server. Please do not commit your work on the playground so that it remains pristine for other developers to work on.

Testing on mobile or a virtual machine

To test the changes on a mobile or virtual machine, you will need to open the source of the iFrame, to do this:

  1. Run yarn dev
  2. Make sure your virtual machine and mobile device are on the same network
  3. Open http://YOUR_IP_ADDRESS:ASSIGNED_PORT/iframe.html?selectedKind=Playground&selectedStory=Playground in your mobile device or virtual machine

Testing in a consuming project

  1. In your terminal, run yarn run build-consumer PROJECT_DIRECTORY from the polaris-react repo

PROJECT_DIRECTORY is where the build will be copied, which must be a sibling of the polaris-react directory.

# Example
yarn run build-consumer polaris-styleguide
  1. In your terminal, open a second tab and run yarn run dev from the polaris-styleguide repository

In the example above, the build is copied to polaris-styleguide/node_modules/@shopify/polaris. And in this case, a rebuild of polaris-styleguide is required after copying the polaris-react build, but may not be the case for all consuming projects.

# Example
cd ../polaris-styleguide/
yarn run build:development

Also, when running yarn install, copied builds will be overwritten and will require running yarn run build-consumer PROJECT_DIRECTORY again.

Visual regression testing

Percy runs for every pull request. Percy is a tool that compares screenshots for every single component we have in the library.

Percy is not always 100% accurate. Since it uses screenshot comparison, even browser sub-pixel rendering differences can cause Percy to ask for user confirmation of whether a change was intended or not. In cases like that, use your best judgement to determine whether you need to address it or not. This is why the choice to approve something or not is always manual. While everyone can view changes, only members of the Shopify team an approve changes.

Manual visual regression testing

To start a server for manually viewing the visual regression testing examples, run yarn run dev.

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

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
You can’t perform that action at this time.