Analytics web components
Analytics web components display ShopifyQL data as charts, tables, and lists. A metric card runs a ShopifyQL query and renders the result. A metrics bar arranges cards in a row.
Use these components to add live analytics to an embedded app without building your own charts.
Anchor to ComponentsComponents
A metric card handles the full lifecycle of a query. It sends the query through App Bridge, waits for the response, formats the values, and renders a visualization. A metrics bar handles layout only and doesn't run ShopifyQL itself.
Each component is a custom element that you add to your HTML.
| Component | What it does |
|---|---|
| Metric card | Renders one ShopifyQL result as a chart, table, or list. |
| Metrics bar | Groups metric cards into a row with consistent spacing and a shared loading state. |
App Bridge loads the ShopifyQL data plugin at window.shopify.shopifyQL. This plugin resolves asynchronously, so it isn't always ready when your code runs. Wait for it before rendering a metric card, or the card will start in an error state.
App Bridge loads the ShopifyQL data plugin at window.shopify.shopifyQL. This plugin resolves asynchronously, so it isn't always ready when your code runs. Wait for it before rendering a metric card, or the card will start in an error state.
Anchor to Access requirementsAccess requirements
Analytics web components read live data through the ShopifyQL data plugin that App Bridge exposes at window.shopify.shopifyQL. The plugin calls the shopifyqlQuery endpoint in the GraphQL Admin API from the browser, so your app needs direct API access along with the same access scopes.
Set up the following in your app before you add analytics web components:
- Enable direct API access by setting
embedded_app_direct_api_accesstotrueunder[access.admin]in your app'sshopify.app.tomlfile, so that your embedded app can call the GraphQL Admin API directly from the browser. Apps configure this themselves, and it doesn't require approval from Shopify. For more information, see App configuration. - Request the
read_reportsaccess scope so that your app can read analytics and reporting data. - Request Level 2 access to protected customer data.
Anchor to Required scriptsRequired scripts
Analytics web components depend on three scripts: App Bridge, Polaris, and the analytics UI script. App Bridge provides the ShopifyQL data plugin that metric cards use to fetch data. Polaris provides the base web components that analytics components build on. The analytics UI script registers ShopifyQL analytics custom elements, including s-shopifyql-metric-card and s-metrics-bar, so you can use them in your app. Add all three as <script> tags in your app's <head>, in the order shown in the example, along with a <meta> tag that holds your app's API key.
Anchor to TypeScriptType
For TypeScript users, Shopify provides a companion npm library for analytics web component types, available at @shopify/analytics-ui-types. You can install this library in your project using yarn or npm. Loading the analytics UI script in your app from cdn.shopify.com/shopifycloud/analytics-ui.js installs the latest version of the components. To keep your types in step, specify @shopify/analytics-ui-types@latest in your package.json file.
Anchor to QueriesQueries
Pass a ShopifyQL query to s-shopifyql-metric-card through the query property. The VISUALIZE clause in your query controls the chart type. Use TYPE line for trends over time, TYPE bar for comparisons, TYPE donut for percentage breakdowns, TYPE list_with_dimension_values for ranked lists, or TYPE table for raw data.
The heading property sets the title at the top of the card. You can also set description for supporting text, size to switch between a full card and a compact KPI, and reportLinkHandle to link the card to a full report.
Anchor to LayoutLayout
Wrap metric cards in s-metrics-bar to lay them out in a row with consistent spacing, sizing, and a shared loading state. The bar sizes the cards for you, so you don't need to set size on each card. When the cards overflow, the row scrolls horizontally.
You can add an s-metrics-bar-date-picker to the bar to show a range selector above the cards. The picker fires a change event when the selection changes, but it doesn't rewrite card queries. Listen for the event and update each card's query with the matching date range.