Metric Card widget

Displays name-value data with an optional sparkline chart. MetricCard is typically used to display numerical metrics or KPIs.

https://kroki.io/svgbob/svg/eNpT0NPFBvS4FGoUQMA3taQoM1nBObEoBcyvAUpg1VHDpZuvkJJYkqgAAfl5usk5mcnZCvm6IJnk_Ly0zHQFFAA0Sx2rWeoAhKIgDg==

In-ports

data JSON - Input data that defines one or more metrics to be displayed and its properties.

config JSON - Configuration parameters.

Out-ports

on-click Bool - Emits boolean true when the user clicks on the widget. The event is emitted only when the widget is in interactive mode.

Overview

Kelp MetricCard is a simple yet versatile widget. You use it to display numerical values or KPIs. In addition to single values, it can also display a mini trend-line in the form of a Sparkline chart. Below are some examples of how to use the widget along with the properties you can use to customize its visual representation.

https://cdn.sanity.io/images/n16unevp/production/15e0c540d1cdd27aca1822ca724846e896a45e7f-618x260.png?fit=max

Creating a Metric Card is very easy. You only need to pass a simple array of objects to the data in-port. Each object defines a metric to be displayed and its properties.

PropertyDescription
nameThe name of the metric.
valueThe value of the metric.
convertorFormatting function. See Value Formatters to learn how to format the values of different data types. Default value is none.
unitCustom unit property for metric. Converter has higher priority'
changeValueValue for change value indicator. Change value will be also displayed if history property is set and calculated based on the last value in history array.
changeValuePercentPercentage value for change value indicator. Has a higher priority than changeValue if both properties are set.
historyAn array of numbers representing historical values of the metric. If defined, the sparkline chart will be displayed.
historyMetaAdditional meta data for the history sparkline chart: {"duration": 6, "unit": "months"}. This properties are used in the tooltip template.

You can switch MetricCard to interactive mode. It will turn into a clickable tile with blue background on a mouse hover. A Boolean true event will be generated every time the user clicks on the widget.

Data input examples

Send the following JSON snippets to the data port to see different representations of the MetricCard widget.

1. Simple metric card

[
{
"name": "Revenue",
"value": 5980000000
}
]

2. Multiple metrics in one card

[
{
"name": "Tesla Inc",
"converter": "numberToHumanReadable",
"value": 1516.8,
"changeValue": 19.74,
},
{
"name": "Revenue",
"converter": "numberToHumanReadable",
"changeValue": 1901640000,
"value": 5980000000,
},
{
"name": "Net income",
"converter": "numberToHumanReadable",
"value": 16000000
}
{
"name": "Operating income",
"converter": "numberToHumanReadable",
"value": 283000000
},
{
"name": "Net profit margin",
"converter": "formatPercent",
"value": 0.0027
}
]

3. Complex metric card with trendline

[
{
"name": "Tesla Inc",
"converter": "numberToHumanReadable",
"value": 1516.8,
"changeValue": 19.74,
"history": [0, 10, 12, 8, 14, 20, 18, 22],
"historyMeta": {
"duration": 6,
"unit": "month"
},
"summary": {
"Open": "1,556.00",
"High": "1,590.00",
"Low": "1,431.00",
"Mkt cap": "281.17B",
"P/E ratio": "-",
"Div yield": "-",
"Prev close": "1,497.06",
"52-wk high": "1,794.99",
"52-wk low": "211.00"
}
}
]

Settings

Title

Widget title. It is displayed in the header of the widget tile. To hide the header, leave the Title property empty.

Hide progress bar

Turn off progress indicator in the header of the widget tile.

Hide help icon

If checked, the Help icon will not be displayed.

Primary metric index

Index of the primary metric. Its the index of the object in the input array on the data port. Note that the index starts from 0. Only one metric can be primary.

Is interactive

Turn on interactive mode. On click, a boolean true event will be sent out on the on-click outport.

Advanced Settings

This widget supports the following advanced properties.

tooltipTemplates

By default tooltip content for primary metric have the following format. You can customize the tooltip by setting the tooltipTemplates property.

{
"tooltipTemplates": {
"primary": "<b>{{metricName}}:</b> {{metricValue}}<br><b>Change:</b> {{changeValue}} ({{changePercent}})<br><b>Period:</b> {{historyDuration}} {{historyUnit}}"
}
}

If changeValue and history props are specified for the primary metric, then a Sparkline chart will be displayed. Hover your mouse over the Sparkline chart to see the tooltip with metricName, historyDuration, and historyUnit. This is the default template for the sparkline chart:

{{metricName}} history over {{historyDuration}} {{historyUnit}} period

Templates are defined as Handlebars templates. The following variables are supported:

  • metricName
  • metricValue
  • changeValue
  • changePercent
  • historyDuration
  • historyUnit
  • accessor

In addition you can use <br> for new line, and <b> for strong text mark up.

tooltipContentAccessors

This parameter allows you to generate tooltip content from custom property defined for the primary metric. Set tooltipContentAccessors parameter as jspath to the property relative to the metric data object.

{
"tooltipContentAccessors": {
"primary": "summary",
"secondary": null
}
}

In this example, the tooltip will be auto-generated from the object defined under summary property of the primary metric card data object. See Example 3: Metric card with a trendline.

Supported value types: String, Number, Array, Object.

Related