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 {
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:
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.
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): [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.
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.
deprecationNotice: String
A deprecation notice for the component if it exists.
Section
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.
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.
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.
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.
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.
Tag
A tag and its value.
Fields
tag: String
The tag name.
text: String
The value of the tag.
MobileContent
Mobile-specific component fields.
Fields
examples: [Example!]!
The mobile examples for the component.
accessibility: String
The mobile accessibility content for the component.
Page
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.
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.