Skip to main content

Metric Card widget

Displays a list of metrics with labels, change over a time period, and a sparkline chart.

component image

In-ports

data Array — input array with one or several more metric objects.

config JSON — configuration parameters.

Out-ports

on-click Boolean — emits true when user clicks on the card. The event is emitted only when the widget is in interactive mode.

Overview

Metric Card lets users quickly view metrics and interpret their values.

Metrics’ labels and their values are always available at glance, plus one metric can be set as primary and display trend over a time period and a sparkline chart. The primary metric can be switched at runtime to call attention to what is most important at the moment.

Metric is defined with an array with an object containing metric properties. Several metrics can be defined with several such objects. To display metrics, pass that array to the data port. To edit widget’s configuration at runtime use the config port.

Examples

Single metric

To display just one metric pass its name and value. This metric is, by default, your primary metric.

metric-card1

[
{
"name": "Tesla Inc",
"value": 1516.8
}
]

List of metrics

To add secondary metrics, add objects defining them.

metric-card2

[
{
"name": "Tesla Inc",
"value": 1516.8
},
{
"name": "Revenue",
"value": 5980000000
},
{
"name": "Net income",
"value": 16000000
}
]

Change over a time period

Make the primary metric indicate an increasing or decreasing trend with an up or down arrow respectively. Add one of the following properties to the primary metric object:

  • changeValue — specifies the difference between the final and initial value.
  • changeValuePercent — specifies the percentage change between the final and initial value.

metric-card3

[
{
"name": "Tesla Inc",
"value": 1516.8,
"changeValue": 19.74
},
{
"name": "Revenue",
"value": 5980000000
},
{
"name": "Net income",
"value": 16000000
}
]

Sparkline chart

You can display a trend with a sparkline chart. Add the history property specifying an array of historical values to the primary metric object.

metric-card4

[
{
"name": "Tesla Inc",
"value": 1516.8,
"changeValue": 19.74,
"history": [1510, 1512, 1504, 1509, 1509, 1515]
},
{
"name": "Revenue",
"value": 5980000000
},
{
"name": "Net income",
"value": 16000000
}
]

If changeValue is not specified, the change will be calculated based on the last historical value.

Tooltip templates

Tooltips appear when you hover mouse over the primary metric or a sparkline chart. Use the Advanced tab to customize tooltip templates.

The default primary metric tooltip’s template is defined as follows:

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

The default sparkline chart’s tooltip is defined similarly:

{
"tooltipTemplates": {
"secondary": "{{metricName}} history over {{historyDuration}} {{historyUnit}} period"
}
}

Note the use of placeholders of the form {{property}} in this example. Placeholders refer to metric properties to display them in the tooltip. A placeholder can use the following properties:

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

Tooltip formatting options include <br> for new line, and <b> for bold text.

Tooltip content accessors

To generate a tooltip based on a property, state it explicitly in the tooltipContentAccessors object. The following value types are supported: String, Number, Array, Object.

Consider the following primary metric example:

[
{
"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"
}
}
]

To generate the primary metric’s tooltip based on its summary property, on the Advanced tab, enter the following configuration:

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

Hover the mouse over the metric’s label to view the tooltip:

metric-card5

Metric properties

PropertyDescription
nameThe name of the metric.
valueThe value of the metric.
converterFormatting function. See Value Formatters to learn how to format the values of different data types. Default value is numberToHumanReadable.
unitCustom unit of measurement for metric. converter has higher priority.
changeValueThe difference between the final and initial value.
changeValuePercentThe percentage change between the final and initial value. Has a higher priority than changeValue` if both properties are set.
historyAn array of numbers representing historical values of the metric. Defines the points for the sparkline chart. Also displays the difference between the last historical value and current value.
historyMetaAdditional meta data for the sparkline chart history: {"duration": 6, "unit": "months"}. These properties can only be shown in the tooltip.

Settings

Title

Sets a widget's title.

Hide progress bar

Controls the visibility of the progress bar. By default, the progress bar is visible.

Is interactive

Controls whether the widget is clickable. When enabled, the on-click port emits true on click.

Primary metric index

Index of the metric you want to highlight. This index corresponds to the index of the object that defines this metric. The indexing starts from 0. The default value is 0.

Primary metric can be switched at runtime. Use the primaryMetricIndex property to set the index through the config port.

Make this field blank to disable primary metric.

Error messages settings

Specifies custom error messages to display inside the widget. You can set a message for each error code.