---
title: Metric card
description: >-
  The metric card component renders the result of a single ShopifyQL query as a
  card and handles data fetching, formatting, loading states, and errors.
api_version: v1.0
source_url:
  html: 'https://shopify.dev/docs/api/analytics-ui/latest/metric-card'
  md: 'https://shopify.dev/docs/api/analytics-ui/latest/metric-card.md'
api_name: analytics-ui
---

# Metric card

The metric card (`s-shopifyql-metric-card`) renders the result of a single [ShopifyQL](https://shopify.dev/docs/api/shopifyql/latest) query as a card. Provide a `query`, and the card fetches data, formats values, renders a chart or table, and handles loading states and errors.

Metric cards read data through `window.shopify.shopifyQL`. To arrange several cards together, use a [metrics bar](https://shopify.dev/docs/api/analytics-ui/latest/metrics-bar).

Metric cards wait for initialization internally. To choose a custom unavailable state, use the [ShopifyQL API](https://shopify.dev/docs/api/analytics-ui/latest/apis/shopifyql-api).

#### Use cases

* **Headline metric**: Show a single KPI like total sales or sessions on an app home or dashboard page.
* **Dimensional breakdown**: Compare a metric across products, channels, or regions with a bar or donut chart.
* **Trend over time**: Chart how a metric moves across a date range with a line chart.
* **Drill-in summary**: Surface a summary metric that links to its full report.
* **Geographic spread**: Show where sales or orders come from on a map.

***

## Properties

The `query` property is required. The rest are optional and control the card's headings, size, report link, and refresh behavior.

| Property | Type | Default | Description |
| - | - | - | - |
| `query` | `string` | — | The `query` property accepts a ShopifyQL query string. See the [ShopifyQL reference](https://shopify.dev/docs/api/shopifyql/latest) for syntax, schemas, and available metrics. |
| `heading` | `string` | — | Primary title at the top of the card. |
| `smallHeading` | `string` | — | Secondary heading below the primary heading. |
| `description` | `string` | — | Supporting text that describes the metric. |
| `size` | `'small' \| 'base'` | `'base'` | Controls the card's size. |
| `variant` | `'auto' \| 'secondary'` | `'auto'` | Visual variant of the card. |
| `summary` | `'auto' \| 'none'` | `'auto'` | Controls whether the card shows the summarized total value. |
| `primaryAction` | `'auto' \| 'none'` | `'auto'` | Controls whether the card shows its primary action. |
| `queryFormatting` | `'auto' \| 'none'` | `'auto'` | Controls whether the query string is auto-formatted before execution. Set to `none` to send the query without changes. |
| `pollingInterval` | `number` | — | Interval, in milliseconds, at which the card refetches its query for live data. Set it only for data that must stay current. |
| `overrideCardQuery` | `string` | — | Overrides the query used for the card's drill-in report link. |
| `reportLinkHandle` | `string` | — | Handle or numeric report ID of the report to open from the card's footer report link. |
| `reportLinkDisabled` | `boolean` | `false` | Turns off the card's report link. |
| `reportLinkTarget` | `'auto' \| '_blank' \| '_self' \| '_top'` | `'auto'` | Where the report link opens. |

### Events

The card exposes one event so you can handle its report link click yourself, like routing to a custom report page.

| Event | Description |
| - | - |
| `reportlinkclick` | Fires when the card's report link is activated. In React, use `onReportLinkClick`. |

***

## Examples

Each example pairs a query you can copy and adapt with the card it renders, ranging from a single value to a grouped breakdown or a multi-metric chart.

##### Show a single metric

Renders one query result as a card. Use it for a headline metric like sales or sessions, with an optional comparison to the previous period.

##### Show a compact KPI

Shrinks the card to a title, value, and percent-change indicator with `size="small"`. Use it in dense layouts and metrics bars.

##### Break a metric down by dimension

Splits a metric across dimension values with [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by) and a [`bar`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#bar-charts) chart. Use it to compare products, channels, or regions. `GROUP BY TOP 3` keeps the three product types that rank highest under `ORDER BY total_sales DESC`, plus an `Other` row aggregating the rest. Use `GROUP BY ONLY TOP 3` to show just the top three.

##### Show a percentage breakdown

Splits a grouped total into slices with a [`donut`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#part-to-whole-and-hierarchy-charts) chart. Use it to compare a few values as shares of the total. The grouped metafield's definition must have the [`analyticsQueryable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#analytics-queryable) capability enabled, or the card returns no data.

##### Rank dimension values in a list

Ranks dimension values in an ordered list with [`list_with_dimension_values`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#tables-and-lists). Use it for top-N views like best-selling variants. `GROUP BY TOP 10` keeps the ten variants that rank highest under `ORDER BY total_sales DESC`, plus an `Other` row aggregating the rest. Use `GROUP BY ONLY TOP 10` to show just the top ten.

##### Show a data table

Renders the result as rows and columns with a [`table`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#tables-and-lists). Use it when exact numbers matter more than visual shape.

##### Combine chart types in one card

Plots several metrics together, each with its own chart type, in one `VISUALIZE` clause. Use it to relate metrics like sales and orders on one card.

##### Plot two metrics on a scatter chart

Plots one metric against another as points with a [`scatter_plot`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#distribution-and-relationship-charts). Use it to spot correlation, clusters, and outliers between two measures.

##### Compare three metrics with a bubble chart

Positions points by two metrics and sizes each one by a third with a [`bubble_chart`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#distribution-and-relationship-charts). Use it to compare entities across three measures at once.

##### Show orders on a map

Groups nearby billing addresses into clusters with `GROUP BY CLUSTER billing_address` and draws each cluster as a bubble on a map with `bubble_map`. Use it to see where orders come from. The latitude and longitude filters in `WHERE` set the area the map shows, and `COMPARE TO` adds each bubble's change from the previous period to its tooltip. The card requires [your app's Google Maps API key](https://shopify.dev/docs/api/analytics-ui/latest/metric-card#google-maps-api-key).

##### Profile a dimension with a radar chart

Plots several metrics on axes radiating from a center with a [`radar`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#radial-charts) chart. Use it to contrast a dimension's values across multiple measures. The grouped metafield's definition must have the [`analyticsQueryable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#analytics-queryable) capability enabled, or the card returns no data.

##### Show nested share with a sunburst chart

Renders a hierarchy as concentric rings with a [`sunburst`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#part-to-whole-and-hierarchy-charts) chart. Use it to explore nested categories and their contribution to the whole. `ORDER BY total_sales DESC` ranks the product types and the products within each type by sales, so each `TOP 3` keeps the best sellers rather than the first three alphabetically.

##### Show a hierarchy with a treemap

Tiles nested, area-sized boxes with a [`treemap`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#part-to-whole-and-hierarchy-charts). Use it to compare contribution across many items at once.

##### Show cumulative change with a waterfall

Breaks a total into sequential contributions with a [`waterfall`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#funnel-flow-and-change-charts) chart. Use it to show how each period builds up to the running total.

##### Handle the report link in React

Handles the footer report link in your app with `onReportLinkClick`. Use it to route to a custom report page. Types come from the `@shopify/analytics-ui-types` package.

## html

```html
<s-shopifyql-metric-card
  heading="Total sales"
  query="FROM sales
    SHOW total_sales
    TIMESERIES day
    WITH TOTALS, PERCENT_CHANGE
    SINCE startOfDay(-90d)
    UNTIL endOfDay(-1d)
    COMPARE TO previous_period
    ORDER BY day ASC
    LIMIT 100
    VISUALIZE total_sales TYPE line"
></s-shopifyql-metric-card>
```

![A metric card titled Total sales showing a line chart of total sales over the last 90 days, with a headline value and a percent-change comparison to the previous period.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-single-metric-light-CqLAMgB3.png)

## html

```html
<s-shopifyql-metric-card
  heading="Total sales"
  size="small"
  query="FROM sales
    SHOW total_sales
    TIMESERIES day
    WITH TOTALS, PERCENT_CHANGE
    SINCE startOfDay(-365d)
    UNTIL endOfDay(-1d)
    COMPARE TO previous_period
    ORDER BY day ASC
    LIMIT 100
    VISUALIZE total_sales TYPE line"
></s-shopifyql-metric-card>
```

![A compact metric card titled Total sales showing the headline value, a percent-change indicator, and a small sparkline.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-compact-kpi-light-CaN6MBHv.png)

## html

```html
<s-shopifyql-metric-card
  heading="Total sales by product type"
  reportlinkhandle="total_sales_over_time"
  query="FROM sales
    SHOW total_sales
    GROUP BY TOP 3 product_type WITH TOTALS
    DURING last_year
    ORDER BY total_sales DESC
    VISUALIZE total_sales TYPE bar"
></s-shopifyql-metric-card>
```

![A metric card titled Total sales by product type showing a bar chart comparing total sales across the top three product types: Beverages, Bakery, and Merch.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-dimension-breakdown-light-Dtytuxyp.png)

## html

```html
<s-shopifyql-metric-card
  heading="Sales share by reward tier"
  query='FROM sales
    SHOW total_sales
    WHERE order.metafields."app--393038102529--loyalty".reward_tier IS NOT NULL
    GROUP BY order.metafields."app--393038102529--loyalty".reward_tier
    WITH TOTALS, PERCENT_CHANGE
    DURING last_year
    COMPARE TO previous_period
    ORDER BY total_sales DESC
    LIMIT 1000
    VISUALIZE total_sales TYPE donut'
></s-shopifyql-metric-card>
```

![A metric card titled Sales share by reward tier showing a donut chart that breaks total sales into Bronze, Silver, Gold, and Diamond reward tiers, with a 1.71 million dollar total in the center.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-percentage-breakdown-light-C4wLLgGT.png)

## html

```html
<s-shopifyql-metric-card
  heading="Top product variants"
  reportlinkhandle="4817253"
  query="FROM sales
    SHOW total_sales
    WHERE product_title IS NOT NULL
    GROUP BY TOP 10 product_variant_title WITH TOTALS, CURRENCY 'USD', PERCENT_CHANGE
    SINCE startOfDay(-90d) UNTIL today
    COMPARE TO previous_period
    ORDER BY total_sales DESC
    VISUALIZE total_sales TYPE list_with_dimension_values"
></s-shopifyql-metric-card>
```

![A metric card titled Top product variants showing a ranked list of the top ten product variants by total sales, each with its value and percent change.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-ranked-list-light-BcOCeSrv.png)

## html

```html
<s-shopifyql-metric-card
  heading="Inventory today by product variant"
  query="FROM inventory
    SHOW ending_inventory_units
    GROUP BY product_title, product_variant_title
    VISUALIZE ending_inventory_units TYPE table"
></s-shopifyql-metric-card>
```

![A metric card titled Inventory today by product variant showing a table of ending inventory units by product title and product variant title.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-data-table-light-CxVEpU3r.png)

## html

```html
<s-shopifyql-metric-card
  heading="Total sales over time"
  query="FROM sales
    SHOW total_sales, orders
    TIMESERIES day
    SINCE startOfDay(-90d) UNTIL endOfDay(-1d)
    ORDER BY day ASC LIMIT 100
    VISUALIZE total_sales TYPE bar, orders TYPE line"
></s-shopifyql-metric-card>
```

![A metric card titled Total sales over time showing daily total sales as bars and orders as an overlaid line over the last 90 days, on dual axes.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-combined-chart-types-light-DGbckuEz.png)

## html

```html
<s-shopifyql-metric-card
  heading="Products by sales and order volume"
  query="FROM sales
    SHOW total_sales, orders
    GROUP BY product_title, product_type
    SINCE startOfDay(-90d) UNTIL endOfDay(-1d)
    ORDER BY total_sales DESC
    LIMIT 100
    VISUALIZE total_sales, orders TYPE scatter_plot"
></s-shopifyql-metric-card>
```

![A metric card titled Products by sales and order volume showing a scatter plot of products positioned by order volume and total sales, with a legend of products and their types.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-scatter-plot-light-DYuMMWLL.png)

## html

```html
<s-shopifyql-metric-card
  heading="Products by sales, orders, and order value"
  query="FROM sales
    SHOW total_sales, orders, average_order_value
    GROUP BY product_title
    SINCE startOfDay(-90d) UNTIL endOfDay(-1d)
    ORDER BY total_sales DESC
    LIMIT 100
    VISUALIZE total_sales, orders, average_order_value TYPE bubble_chart"
></s-shopifyql-metric-card>
```

![A metric card titled Products by sales, orders, and order value showing a bubble chart where each product is positioned by orders and total sales and sized by average order value.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-bubble-chart-light--IUIi3bS.png)

## html

```html
<s-shopifyql-metric-card
  heading="Orders"
  query="FROM sales
    SHOW total_sales, orders
    WHERE billing_address.latitude >= 24.98129502344942
      AND billing_address.latitude <= 51.16227141222271
      AND billing_address.longitude >= -159.08203125
      AND billing_address.longitude <= -30.41015625
    GROUP BY CLUSTER billing_address WITH TOTALS, PERCENT_CHANGE, CURRENCY 'USD'
    SINCE 2025-07-01 UNTIL 2025-08-31
    COMPARE TO previous_period
    ORDER BY orders DESC
    VISUALIZE orders TYPE bubble_map"
></s-shopifyql-metric-card>
```

![A metric card titled Orders showing a map of the United States with blue bubbles sized by order count, clustered by billing address. The largest bubble, about 1K orders, is in the Northeast, and a size legend sits in the lower-left corner.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-bubble-map-light-7LcdZPDz.png)

## html

```html
<s-shopifyql-metric-card
  heading="Sales profile by reward tier"
  query='FROM sales
    SHOW total_sales, orders, average_order_value
    WHERE order.metafields."app--393038102529--loyalty".reward_tier IS NOT NULL
    GROUP BY order.metafields."app--393038102529--loyalty".reward_tier WITH TOTALS
    DURING last_year
    ORDER BY total_sales DESC
    VISUALIZE total_sales, orders, average_order_value TYPE radar'
></s-shopifyql-metric-card>
```

![A metric card titled Sales profile by reward tier showing a radar chart that profiles Bronze, Silver, Gold, and Diamond reward tiers across total sales, orders, and average order value.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-radar-chart-light-CoySdbur.png)

## html

```html
<s-shopifyql-metric-card
  heading="Sales by category and product"
  query="FROM sales
    SHOW total_sales
    GROUP BY ONLY TOP 3 product_type, ONLY TOP 3 product_title WITH GROUP_TOTALS, TOTALS
    DURING last_year
    ORDER BY total_sales DESC
    VISUALIZE total_sales TYPE sunburst"
></s-shopifyql-metric-card>
```

![A metric card titled Sales by category and product showing a sunburst chart with an inner ring of product types (Beverages, Bakery, and Merch) and an outer ring of products within each type.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-sunburst-light-DZZnwtX4.png)

## html

```html
<s-shopifyql-metric-card
  heading="Sales by category and product"
  query="FROM sales
    SHOW total_sales
    GROUP BY product_type, product_title WITH GROUP_TOTALS, TOTALS
    DURING last_year
    ORDER BY product_type ASC, total_sales DESC
    VISUALIZE total_sales TYPE treemap MAX 5"
></s-shopifyql-metric-card>
```

![A metric card titled Sales by category and product showing a treemap of nested tiles grouped by product type (Beverages, Bakery, Merch) and sized by each product's total sales.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-treemap-light-DUAkbdzN.png)

## html

```html
<s-shopifyql-metric-card
  heading="Total sales by month"
  query="FROM sales
    SHOW total_sales
    TIMESERIES month WITH TOTALS
    DURING last_year
    ORDER BY month ASC
    VISUALIZE total_sales TYPE waterfall"
></s-shopifyql-metric-card>
```

![A metric card titled Total sales by month showing a waterfall chart where each month of the last year adds to a cumulative total sales bar.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-waterfall-light-D_pVlq5u.png)

## tsx

```tsx
import type {CallbackEvent} from '@shopify/analytics-ui-types';


function SalesCard() {
  function handleReportLinkClick(
    event: CallbackEvent<'s-shopifyql-metric-card'>,
  ) {
    event.preventDefault();
    window.location.assign('/reports/total-sales');
  }


  return (
    <s-shopifyql-metric-card
      heading="Total sales"
      query="FROM sales SHOW total_sales
        TIMESERIES day
        SINCE startOfDay(-30d) UNTIL endOfDay(-1d)
        VISUALIZE total_sales TYPE line"
      onReportLinkClick={handleReportLinkClick}
    ></s-shopifyql-metric-card>
  );
}
```

![A metric card titled Total sales showing a line chart of daily total sales over the last 30 days.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-report-link-light-DvPZduC-.png)

***

## Bubble maps

To create a bubble map, add `TYPE bubble_map` to your query’s [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize) clause.

A `bubble_map` card works differently from the other visualizations in a few ways:

* **It needs a Google Maps API key**: Your app supplies its own key in a `<meta>` tag. Without it, the card doesn't draw the map. For setup steps, refer to [Google Maps API key](https://shopify.dev/docs/api/analytics-ui/latest/metric-card#google-maps-api-key).
* **It plots clusters, not individual addresses**: `GROUP BY CLUSTER` on an address, like `billing_address` or `shipping_address`, returns one row per cluster of nearby addresses, with the cluster's position and address count. The card draws one bubble per row, sized by the visualized metric.
* **You can frame a region**: Add latitude and longitude filters on the clustered address to `WHERE`. The card fits the map to those bounds, and Shopify sizes the clusters for that area. Without them, the card fits the map to the bubbles.
* **It supports comparisons**: Add [`COMPARE TO`](https://shopify.dev/docs/api/shopifyql/latest/syntax/compare-to) to show each bubble's change from the comparison period in its tooltip.
* **It needs a full-size card**: A card with `size="small"` doesn't draw a map. Keep the default `size="base"` and give the card enough height for the map to be readable.
* **It doesn't refetch when the map moves**: Users can pan and zoom the map, but the card doesn't rerun the query for the new view. The bubbles stay as your query returned them.

### Google Maps API key

Metric cards that use the `bubble_map` visualization draw their data on Google Maps. Shopify doesn't provide a Google Maps API key to apps, so your app supplies its own. Cards that don't render a map don't need a key.

To set up the key, complete the following steps:

1. Create an API key in your own Google Cloud project and enable the Maps JavaScript API for it. For more information, refer to the [Google Maps Platform documentation](https://developers.google.com/maps/documentation/javascript/get-api-key).
2. Restrict the key to the websites that serve your app. Metric cards render inside your app's iframe, so Google checks your app's origin, not `admin.shopify.com`. Include the hosts that you use during development, like `localhost` or your tunnel's domain.
3. Add the key to your app's `<head>` in a `<meta>` tag named `analytics-ui:google-maps-api-key`, as shown in the example. The tag must be on the page before the card renders.

Google bills map loads to the Google Cloud project that owns the key. You don't need a map ID, because the card applies its own map styling.

**Note:**

If the `analytics-ui:google-maps-api-key` tag is missing or empty, the card doesn't draw the map.

## HTML

```html
<head>
  <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
  <meta name="analytics-ui:google-maps-api-key" content="%GOOGLE_MAPS_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  <script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
  <script src="https://cdn.shopify.com/shopifycloud/analytics-ui-1.js"></script>
</head>
```

Metric cards that use the `bubble_map` visualization also load the Maps JavaScript API from Google, so the example policy blocks them. If your app renders map cards, then also allow the sources that Google lists in its [Content Security Policy guide](https://developers.google.com/maps/documentation/javascript/content-security-policy).

***

## Best practices

These practices keep each card focused and its visualization suited to the data.

* **Keep each card focused**: Give every card one metric so users can read it at a glance. When you have several related metrics, lay them out in a [metrics bar](https://shopify.dev/docs/api/analytics-ui/latest/metrics-bar).
* **Match the visualization to the data**: Use `TYPE line` for trends over time, `TYPE bar` or `TYPE donut` for grouped dimensions, `TYPE list_with_dimension_values` for ranked lists, and `TYPE bubble_map` for locations.
* **Link to the underlying report**: Set `reportLinkHandle` so users can open the full report when a summary card raises a question.

***
