KPI

A KPI is a number first. The card prints a label, a formatted value, and a delta. A sparkline can sit under the figure. There is no dial and no scale.

When to use it

Use a KPI when the question is the figure, and how it moved. Revenue at 125,000, up 12.5 percent, with a short sparkline, is that chart. Green beans is the same card when a lower bill is the good direction.

A gauge puts one reading on a dial, with ticks and a needle. Use it when the position on a scale is the point. A progress ring is a share of a maximum. A sparkline is the trend alone, with no label and no delta. Pass the number array on a KPI when the figure and the trend belong together.

One card is one metric. A row of cards is several specs. The chart does not compare categories.

KPI and gauge

Both take a metric object. The type decides the drawing.

type: "kpi" prints metric.value large. metric.delta is the change, as a fraction unless metric.deltaFormat says otherwise. 0.125 is +12.5 percent with the default delta format. The arrow follows the sign.

type: "gauge" is the dial. metric.min and metric.max are the scale. A KPI ignores that scale. Do not put value or delta at the top of the spec. They belong under metric.

Data

metric.value is required. metric.label is the line above it. metric.format is a preset, such as compact, number, or percent, or an object for currency, decimals, and a suffix. Green beans uses a currency object. Churn uses a number with one decimal and a percent suffix.

data is an optional list of numbers. Two or more numbers draw a sparkline. The field name is value. You do not set encoding for that line. Omit data and the card is the figure only.

metric.goodDirection is up or down. Omit it and up is good: a positive delta uses the positive color, and a negative delta uses the negative color. Down reverses that, which is what you want for a cost or a churn rate.

metric.thresholds colors the card surface. Each step is value and color. The last step at or below metric.value wins. A value under every step still uses the first. The label on a step is not drawn.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest KPI. version, type, metric.value, and a11y.alt are required. The delta is optional. There is no sparkline until you pass data. Up is the good direction, and the surface stays the theme surface.

spec.json
{
  "version": "1",
  "type": "kpi",
  "metric": {
    "label": "Tickets",
    "value": 18,
    "delta": -0.05
  },
  "a11y": {
    "alt": "Open tickets are 18, slightly down."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/kpiBundle@chartkitdev/core/allFamilyCore
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing KPI specs. Revenue is the core example: compact format, a rising delta, and a sparkline. Green beans is a currency card where down is good. Churn colors the surface from three steps and also treats down as good. A size in the spec wins. Green beans is 420 by 240. Churn is 300 by 96.

Good when

metric.goodDirection chooses which way of metric.delta is good. Omit it, or leave it unset, and up is good. down paints a falling delta with the positive color and a rising delta with the negative color.

Green beans and Churn set down. Revenue omits the key. Up removes the key, so the default stays omitted. Down writes down.

metric.goodDirection
{
  "metric": { "goodDirection": "down" }
}

metric.deltaFormat formats the delta. The default is a signed percent. Change it in the playground.

Format

metric.format formats the big number. compact, number, and percent are the presets a first card sets. Revenue uses compact.

A currency, a decimal count, or a suffix is an object. Green beans and Churn use objects, so none of the preset buttons start pressed. Choosing a preset writes that string and replaces the object. Switch examples to get the object back. The object itself stays in the playground.

metric.format
{
  "metric": { "format": "compact" }
}

Sparkline

data is a list of numbers. The card draws a filled line through them, under the value. Omit it and there is no line. A single number is not enough. The line needs two points.

Off removes data. On puts that example's array back. An example that omitted the array stays a number only. This is not type: "sparkline". The KPI keeps the label, the value, and the delta.

data
{
  "data": [10, 12, 9, 14, 18, 17]
}

mark.strokeWidth and mark.fillOpacity tune the line. Churn sets both. Change them in the playground. Sampling does not apply to a KPI and warns CK3010.

Thresholds

metric.thresholds colors the whole card from the value. Steps are ordered by value. The last step at or below the value wins. Churn is teal under 3, sand from 3, and red from 5, so 2.4 stays on the first step.

Off removes the list and the surface returns to the theme. On puts that example's steps back. An example that omitted them gets one step at 0 with the positive color, so the card changes and you can see the key. A bad list, such as two steps with the same value, warns CK3082 and the surface stays plain.

metric.thresholds
{
  "metric": {
    "thresholds": [
      { "value": 0, "color": "positive" }
    ]
  }
}

Tooltip

The card already prints the label, the value, and the delta. tooltip is the hover card, the same key as on a bar. Omit it and this control reads on. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields and tooltip.position stay in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed.

The rest of the spec

A KPI does not use a legend. There is one figure. metric.deltaFormat and the sparkline stroke stay in the playground, with the theme presets and the full option list.