Metrics bar
The metrics bar (s-metrics-bar) lays out metric cards in a row with consistent spacing, sizing, and a shared loading state. It handles layout only and doesn't fetch data or run ShopifyQL. Add metric cards as children, and the row scrolls horizontally when the cards overflow.
The bar can also include a date range picker. The picker emits a change event, but it doesn't rewrite card queries. Listen for the event and update each card's query.
Anchor to PropertiesProperties
All three properties are optional. Set accessibilityLabel to describe the row, and loading to show a shared loading state.
| Property | Type | Default | Description |
|---|---|---|---|
loading | boolean | false | Renders the bar and its cards in a loading state. Use it while the ShopifyQL plugin or queries are resolving. |
variant | 'auto' | 'secondary' | 'auto' | Visual variant of the bar. |
accessibilityLabel | string | — | Accessible label that describes the contents of the bar. |
Anchor to SlotsSlots
The default slot accepts metric card children, which render in the order they appear. It also accepts one optional s-metrics-bar-date-picker, which renders above the cards. The bar sizes its cards for you, so you don't need to set size on each card.
Anchor to Date range pickerDate range picker
Add an s-metrics-bar-date-picker as a child of the bar to show preset date ranges above the row.
The picker doesn't rewrite card queries. When the selection changes, the picker fires a change event that exposes the new range alias on event.currentTarget.value. In React, use onChange. Listen for that event and update each card's query with the matching SINCE clause.
| Property | Type | Default | Description |
|---|---|---|---|
value | 'today' | 'last7days' | 'last30days' | 'last90days' | 'last365days' | — | The currently selected preset range. |
disabled | boolean | false | Renders the picker as disabled. |
Anchor to EventsEvents
The date picker exposes one event so you can update your cards' queries when a user changes the range.
| Event | Description |
|---|---|
change | Fires when the selected range changes. The new range alias is available on event.currentTarget.value. In React, use onChange. |
Anchor to Customizing the optionsCustomizing the options
By default, the picker includes today, last7days, and last30days. To change which presets appear, add s-metrics-bar-date-option children. Each option must use one of the supported aliases: today, last7days, last30days, last90days, or last365days.
| Property | Type | Default | Description |
|---|---|---|---|
value | 'today' | 'last7days' | 'last30days' | 'last90days' | 'last365days' | — | The preset range that this option represents. |
disabled | boolean | false | Renders the option as disabled. |
Anchor to ExamplesExamples
Each example pairs a row layout you can copy and adapt with the bar it renders, ranging from a basic set of metrics to a picker-driven row that updates on range changes.
Lay out a row of metric cards
Arranges several metric cards in one row with consistent spacing and sizing. Use it for a set of related headline metrics, like total, net, and gross sales over 30 days.
Build a compact KPI row
The bar renders cards in a compact layout. Use it for a dense row of single-value metrics with titles, current values, and percent-change indicators.
Mix visualization types in one bar
Each card in a bar can visualize its query differently. This row combines a donut chart, a line chart, and a bar chart. The Sales by campaign card groups by a custom metafield, whose definition must have the analyticsQueryable capability enabled, or that card returns no data.
Add a date range picker
Add an s-metrics-bar-date-picker to the bar to show a range selector above the cards. By default, it includes today, the last seven days, and the last 30 days.
Customize the date range options
Add s-metrics-bar-date-option children to control which presets the picker shows.
Respond to date range changes in React
The picker doesn't rewrite card queries. Keep the selected range in state, listen for onChange, and rebuild each card's query with the matching SINCE clause. Types come from the @shopify/analytics-ui-types package.
Show a loading state
Set loading on the bar to render one loading state for the whole row.
Anchor to Best practicesBest practices
These practices keep the row accessible and let the bar manage its own layout.
- Let the bar own layout: Add cards as children and let the bar size and scroll them. You don't need to set
sizeon each card or manage the row yourself. - Provide an accessibility label: Set
accessibilityLabelto describe what the bar contains for assistive technologies.