---
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: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/shopifyql/latest/web-components/metric-card'
  md: 'https://shopify.dev/docs/api/shopifyql/latest/web-components/metric-card.md'
api_name: shopifyql
---

# 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/shopifyql/latest/web-components/metrics-bar).

**Caution:**

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.

#### 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.

***

## 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 ShopifyQL query whose result the card renders. The [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize) clause sets the chart type. |
| `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` returns the top three 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` returns the top ten 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.

##### 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.

##### 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-next/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-next/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-next/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-next/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-next/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-next/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-next/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-next/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-next/shopifyql-metric-card-bubble-chart-light--IUIi3bS.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-next/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 product_type ASC, 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-next/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-next/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-next/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-next/shopifyql-metric-card-report-link-light-DvPZduC-.png)

***

## 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/shopifyql/latest/web-components/metrics-bar).
* **Match the visualization to the data**: Use `TYPE line` for trends over time, `TYPE bar` or `TYPE donut` for grouped dimensions, and `TYPE list_with_dimension_values` for ranked lists.
* **Link to the underlying report**: Set `reportLinkHandle` so users can open the full report when a summary card raises a question.

***