GraphQL 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:

• Edit on CodePen
• Run the pages query in GraphiQL

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

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:

• Edit on CodePen
• Run the components query in GraphiQL

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

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…

• Edit on CodePen
• Run the design tokens query in GraphiQL

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.

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.

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.

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.

A section in the document.

Fields

label: String

The label of the section.

htmlId: String

The id of the section (in kebab-case, for use in the HTML).

keywords: String

The keywords of the section.

html: String

The content (in HTML format) of the section.

markdown: String

The content (in Markdown format) of the section.

showInNavigation: Boolean

Describes if the section should appear in the navigation.

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.

fullSizeExamples: Boolean

Remove space around examples when rendered.

accessibility: String

The web accessibility content for the component.

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.

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.

embeddedAppOnly: Boolean

Whether the prop is for embedded apps only or not.

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.

Mobile-specific component fields.

Fields

examples: [Example]

The mobile examples for the component.

accessibility: String

The mobile accessibility content for the component.

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.

intro: String

The intro of the page.

sections: [Section]

The sections of the page.

keywords: String

The keywords of the page.

A category that the page accepts.

Fields

name: String

The name of the category.

slug: String

The slug of the category.

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.