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 {
        name
        slug
        subtype
        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, and more.

• 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): [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.

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.

deprecationNotice: String

A deprecation notice for the component if it exists.

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.

omitAppProvider: Boolean

Prevents automatic wrapping of examples with an AppProvider.

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.

tags: [Tag!]

A list of all tags associated with a 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.

A tag and its value.

Fields

tag: String

The tag name.

text: String

The value of the tag.

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

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.

subtype: String

The subtype of the page.

sections: [Section!]!

The sections of the page.

keywords: String

The keywords of the page.

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.