@shopify/polaris

What is @shopify/polaris?

@shopify/polaris is a React component library designed to help developers create high-quality, consistent user interfaces for Shopify apps. It provides a wide range of pre-built components and styles that adhere to Shopify's design guidelines, making it easier to build applications that look and feel like native Shopify experiences.

What are @shopify/polaris's main functionalities?

Button

The Button component is used to trigger actions. It can be customized with different styles, sizes, and behaviors.

import { Button } from '@shopify/polaris';

function MyComponent() {
  return (
    <Button onClick={() => alert('Button clicked!')}>Click me</Button>
  );
}

Card

The Card component is used to group related content and actions. It provides a structured layout with a title and content area.

import { Card } from '@shopify/polaris';

function MyComponent() {
  return (
    <Card title="Card title" sectioned>
      <p>Card content goes here.</p>
    </Card>
  );
}

Form

The Form component is used to collect user input. It includes various input fields and a submit button, all wrapped in a form layout.

import { Form, FormLayout, TextField, Button } from '@shopify/polaris';

function MyComponent() {
  return (
    <Form onSubmit={() => alert('Form submitted!')}>
      <FormLayout>
        <TextField label="Name" onChange={() => {}} autoComplete="name" />
        <TextField type="email" label="Email" onChange={() => {}} autoComplete="email" />
        <Button submit>Submit</Button>
      </FormLayout>
    </Form>
  );
}

Page

The Page component is used to structure the main content of a page. It includes a title and a content area.

import { Page } from '@shopify/polaris';

function MyComponent() {
  return (
    <Page title="Page title">
      <p>Page content goes here.</p>
    </Page>
  );
}

Modal

The Modal component is used to display content in a layer above the main application. It can be used for dialogs, forms, or additional information.

import { Modal, Button } from '@shopify/polaris';
import { useState } from 'react';

function MyComponent() {
  const [active, setActive] = useState(false);

  return (
    <div>
      <Button onClick={() => setActive(true)}>Open Modal</Button>
      <Modal
        open={active}
        onClose={() => setActive(false)}
        title="Modal title"
        primaryAction={{
          content: 'Close',
          onAction: () => setActive(false),
        }}
      >
        <Modal.Section>
          <p>Modal content goes here.</p>
        </Modal.Section>
      </Modal>
    </div>
  );
}

Other packages similar to @shopify/polaris

material-ui

Material-UI is a popular React component library that implements Google's Material Design. It offers a wide range of customizable components and themes, making it a versatile choice for building modern web applications. Compared to @shopify/polaris, Material-UI is more general-purpose and not specifically tailored for Shopify apps.

ant-design

Ant Design is a comprehensive React UI library with a focus on enterprise-level applications. It provides a large set of high-quality components and design guidelines. While Ant Design is more feature-rich and suitable for a variety of applications, @shopify/polaris is specifically designed for Shopify app development.

blueprintjs

Blueprint is a React-based UI toolkit for the web, optimized for building complex, data-dense interfaces. It offers a range of components and is particularly well-suited for desktop applications. Compared to @shopify/polaris, Blueprint is more focused on data-heavy applications and less on e-commerce.

semantic-ui-react

Semantic UI React is the official React integration for Semantic UI. It provides a set of components that follow the Semantic UI design principles, making it easy to create responsive and themable web applications. While Semantic UI React is versatile and easy to use, @shopify/polaris is specifically designed for creating Shopify apps.

README

Polaris React

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.

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/build/esm/styles.css';

Otherwise include the CSS in your HTML. We suggest copying the latest styles file into your own project. This will need to be updated with future releases.

<link rel="stylesheet" href="styles.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, LegacyCard, Button} from '@shopify/polaris';

1. Tell React to render the element in the DOM:

ReactDOM.render(
  <AppProvider i18n={enTranslations}>
    <Page title="Example app">
      <LegacyCard sectioned>
        <Button onClick={() => alert('Button clicked!')}>Example button</Button>
      </LegacyCard>
    </Page>
  </AppProvider>,
  document.querySelector('#app'),
);

1. Load the web font Inter.

<link rel="preconnect" href="https://cdn.shopify.com/" />
<link
  rel="stylesheet"
  href="https://cdn.shopify.com/static/fonts/inter/v4/styles.css"
/>

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 latest styles file into your own project. This will need to be updated with future releases.

<link rel="stylesheet" href="styles.css" />

1. Include the markup and associated classes in your HTML document:

<button class="Polaris-Button">Example button</button>

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?path=/story/playground-playground--playground in your mobile device or virtual machine

Testing in a consuming project

The /snapit GitHub comment command in pull requests will publish a snapshot NPM package for testing. Read the release documentation for more information.

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:

• Online training courses at reacttraining.com, buildwithreact.com, and reactforbeginners.com.
• The community resources in Awesome React.
• As questions and find answers in the various React support communities.

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