Gauge
A gauge is one number on a dial. The arc runs from metric.min to metric.max. Ticks mark that scale. A needle and a filled arc show metric.value. The same number is printed in the center.
When to use it
Use a gauge when the question is where one reading sits on a scale. Capacity at 72, with a low band and an OK band, is that chart. Readiness is the same idea: one needle, two bands, a stored target.
A progress ring is a share of a maximum on a full circle. It has no needle and no ticks. A KPI is the number first: a label, a value, a delta, and an optional sparkline. It is not a dial. A bullet is the straight form of a measure against a target and ranges. One gauge is one reading. Several measures belong on a bullet.
The default sweep is three quarters of a circle, open at the bottom. That is the dial. A full circle with a needle is still a gauge. It does not become a progress ring.
Gauge, progress ring, and KPI
All three can show one number. The drawing is what changes.
type: "gauge" puts the number on an arc with ticks and a needle. The center prints the formatted value, not a percent of the range. metric.bands paints ranges inside the arc. metric.target is stored on the track as data-ck-target. It is not drawn as a dot or a second needle.
type: "progress-ring" draws the share of metric.max on a circular track. The center is that share unless you set metric.format. There is no needle.
type: "kpi" prints the number large, with a delta beside it. There is no scale. A sparkline, when you pass data, sits under the figure.
Data
The number lives in metric, not in data and not at the top of the spec. metric.value is required. metric.min defaults to 0 and metric.max defaults to 100. metric.label is the caption under the readout.
metric.format formats the readout and the ticks. Capacity uses integer. An object sets decimals or a suffix. Omit it and the readout is a plain number.
metric.target is the goal you want recorded with the chart. Water used sets 80. The needle still points at the value. A drawn target marker is a bullet.
metric.bands is a list of from, to, color, and an optional label. The color may be a token such as positive or negative. metric.thresholds is a KPI key. On a gauge it warns CK3083 and does not color the dial.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest gauge. version, type, metric.value, and a11y.alt are required. The sweep, the cap, and the arc width can be omitted. The dial starts at -135° and ends at 135°. The cap is butt.
{
"version": "1",
"type": "gauge",
"metric": {
"label": "Capacity",
"value": 64,
"min": 0,
"max": 100
},
"a11y": {
"alt": "Capacity is 64 out of 100."
}
}Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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 gauge specs. Capacity is the core example, with a low band and an OK band. Readiness uses the same scale and names the bands Hold and Go. Water used stores a target and sets no bands. A size in the spec wins over the preview default. Readiness is 420 by 250. Water used is 420 by 280.
Bands
metric.bands paints ranges inside the dial, from the worst side of the scale toward the best. Each band needs from and to. color is a token or a CSS color. label is the name in the band's accessible name.
Omit the list and the dial has no inner ranges. Capacity and Readiness set two bands. Water used omits them. Off removes the list. On puts that example's bands back. An example that omitted them gets a low band and an OK band across its own min and max.
{
"metric": {
"bands": [
{ "from": 0, "to": 50, "color": "negative", "label": "Low" },
{ "from": 50, "to": 100, "color": "positive", "label": "OK" }
]
}
}Sweep
mark.startAngle and mark.endAngle are the arc, in degrees. 0 is the top. Positive degrees run clockwise. Omit both and the gauge is a dial: -135° to 135°, open at the bottom.
Half sets -90° to 90°, the top semicircle. Full sets 0° to 360°. The needle and the ticks follow the same sweep. A full gauge is still type: "gauge". A progress ring has no needle.
Any other pair leaves the buttons unpressed. The demo does not hide a sweep it does not list.
{
"mark": { "startAngle": -90, "endAngle": 90 }
}Cap
mark.linecap is the end of the track and the value arc. Omit it, or set butt, and the ends are flat. That is the gauge default. round and square extend the stroke past the angle. The needle still sits on the value.
mark.strokeWidth is the arc thickness in pixels. Omit it and the dial picks a width that fits. Set it in the playground when the fitted width is wrong.
{
"mark": { "linecap": "round" }
}Tooltip
The dial already prints the number, the caption, and the ticks. 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": true
}tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed, so the on state stays omitted.
The rest of the spec
A gauge does not use a legend. The reading is one number. mark.sampling does not apply and warns CK3010. Theme presets live on the playground, with the full option list.