GraphQL API

This site uses a GraphQL API for fetching content. It can be used to build Sketch plugins, text editor extensions, or even a completely new site.

The read-only API is publicly available at the https://polaris.shopify.com/api endpoint. Check out the GraphiQL playground to try out some queries.

⚠️ The API design is currently experimental and subject to change as the needs of its users evolve over time.
We plan to make more data available, such as design tokens, compiled (HTML) examples, and more. Open an issue on GitHub to share your feedback and ideas.

Fetching content from the API

Pages

Here’s a simple JavaScript example that runs a query loading all pages and their content, then displays the result in the console:

const body = JSON.stringify({
  query: `
    {
      pages {
        category {
          name
          slug
        }
        order
        name
        slug
        icon
        content
        sections {
          id
          label
          keywords
        }
        keywords
      }
    }
  `,
});

fetch('https://polaris.shopify.com/api', {
  method: 'post',
  headers: {'Content-Type': 'application/json'},
  body,
})
  .then((response) => response.json())
  .then((json) => console.log(JSON.stringify(json, null, 2)));

Components

Here’s a more advanced example that runs a query loading all components and their content, then displays the result in the console:

const body = JSON.stringify({
  query: `
    query ComponentsQuery($componentSlug: String) {
      componentQuery: componentQuery(slug: $componentSlug){
        componentLinks: components {
          name
          slug
          category
          keywords
        }
        components {
          name
          slug
          category
          intro
          content
          platforms
          web {
            reactName
            hidePlayground
            properties {
              name
              type
              mandatory
              description
            }
            examples {
              name
              description
              slug
              code
            }
          }
          ios {
            examples {
              name
              description
              slug
              code
            }
          }
          android {
            examples {
              name
              description
              slug
              code
            }
          }
          keywords
        }
      }
    }
 `,
});

fetch('https://polaris.shopify.com/api', {
  method: 'post',
  headers: {'Content-Type': 'application/json'},
  body,
})
  .then((response) => response.json())
  .then((json) => {
    console.log(JSON.stringify(json, null, 2));
  });

Design tokens

Polaris Design tokens are open source on GitHub (polaris-tokens repository), available via npm (@shopify/polaris-tokens) and RubyGems (polaris_tokens), as well as via the GraphQL API. Fetching this data from the GraphQL API can be useful to document colors, spacing, font stacks…

const body = JSON.stringify({
  query: `
    {
      designTokens {
        name
        value
        originalValue
        type
        category
        comment
      }
    }
  `,
});

fetch('https://polaris.shopify.com/api', {
  method: 'post',
  headers: {'Content-Type': 'application/json'},
  body,
})
  .then((response) => response.json())
  .then((json) => console.log(JSON.stringify(json, null, 2)));

For larger applications

The examples above are simple demos that may not scale to your project’s needs.

To fetch data in medium to large applications, we recommend using a complete solution such as the Apollo client.

RootQueryType

The root query for this API returns data about both components and pages

Fields

componentQuery([object Object]): ComponentQuery

Name Type Description
slug String The url slug that refers to an individual component.

pages(slug : String, categorySlug : String, order : Int): [Page]

Name Type Description
slug String The url slug that refers to an individual page.
categorySlug String The url slug that refers to the category of an individual page.
order Int The order individual pages show up in the sidebar.

designTokens: [DesignToken]

Returns design tokens data.

ComponentQuery

The format of the query that returns components.

Fields

errors: String

List of errors returned by a failing query

components: [Component]

List of components that match the given query.

Component

A component in the system.

Fields

name: String

The name of the component.

slug: String

The slug of the component.

category: String

The category of the component.

order: Int

The order of the component.

intro: String

The intro content of the component.

sections: [Section]

The sections of the component.

content: String

The content of the component.

platforms: String

The component’s examples availability for each platform.

web: WebContent

The component’s content for the web platform.

ios: MobileContent

The component’s examples for the iOS platform.

android: MobileContent

The component’s examples for the Android platform.

keywords: String

The keywords of the component.

Section

A section in the document.

Fields

label: String

The label of the section.

id: String

The id of the section.

keywords: String

The keywords of the section.

WebContent

Web-specific component fields.

Fields

examples: [Example]

The examples for the component.

properties: [Property]

The properties for the component.

reactName: String

The React name of the component.

hidePlayground: Boolean

Hide the preview in code examples.

Example

An example for a component.

Fields

name: String

The name of the example.

description: String

The description of the example.

code: String

The code for the example.

slug: String

The slug of the example.

Property

A property that the component accepts.

Fields

path: String

The url path for the property.

parentPath: String

The url path for the parent property.

name: String

The name of the property.

type: String

The type of the property.

kind: String

The kind of type it is.

defaultValue: String

The default value for the property.

returnType: Property

The return type of the method.

mandatory: Boolean

Whether the prop has to be provided or not.

description: String

The description of the property.

types: [Property]

The nested types for the property.

MobileContent

Mobile-specific component fields.

Fields

examples: [Example]

The examples for the component.

Page

A page in the system.

Fields

category: Category

The category of the page.

order: Int

The order of the page.

name: String

The name of the page.

slug: String

The slug of the page.

icon: String

The icon of the page.

content: String

The content of the page.

sections: [Section]

The sections of the page.

keywords: String

The keywords of the page.

Category

A category that the page accepts.

Fields

name: String

The name of the category.

slug: String

The slug of the category.

DesignToken

A design token object, most noticeably featuring a name and a value.

Fields

name: String

The name of the design token.

value: String

The value of the design token.

originalValue: String

The original value of the design token as authored in the source file.

comment: String

A comment or the description associated to the design token.

type: String

The type of the design token, for example: string, number, color.

category: String

The category of the design token, for example: background-color, text-color, spacing.