Progress ring
A progress ring is one value between a minimum and a maximum, drawn as an arc on a circular track. The center states the share, or the value when you format it. There is no needle and there are no slices.
When to use it
Use a progress ring when the question is how far one amount is toward its maximum. Uptime at 99.2 out of 100 is that chart. Checks closed, 7 of 10, is the same chart with a smaller maximum.
A donut and a pie split one total into parts. The angle is the share of the whole. A progress ring is not parts of a whole. The track is the full range, and the arc is one value along it. A gauge is a dial: ticks, a needle, and a sweep that opens at the bottom. A KPI prints the number with a delta and no ring.
Several goals on one chart are concentric rings, not extra slices. Activity draws move, exercise, and stand. The first ring is the outside.
Progress ring, donut, and gauge
type: "progress-ring" reads metric.value, metric.min, and metric.max. The arc length is that fraction. Omit metric.format and the center prints the fraction as a percent. Set a format and the center prints the value.
type: "donut" and type: "pie" use encoding.x and encoding.y. Each row is a slice. There is no metric. Closing or opening a hole does not turn a ring into a donut.
type: "gauge" adds ticks and a needle. Its default sweep is -135° to 135°. A progress ring defaults to a full circle, 0° to 360°, and the default cap is round. metric.bands and metric.target belong on a gauge. They are not how a ring shows a goal.
Data
The number lives in metric. metric.value is required. metric.min defaults to 0 and metric.max defaults to 100. metric.label is the caption under the center figure.
metric.format is a preset or an object. Uptime uses one decimal and a percent suffix, so the center reads 99.2% rather than the share 99%. Checks closed uses zero decimals, so the center reads 7 rather than 70%.
mark.rings is a list of value, max, color, and an optional label. The first item is the outer ring. Each ring's length is its own value divided by its own max. Labels are drawn under the rings. With labels, the center caption from metric is not drawn. Activity is that spec. A ring list on another chart type warns CK3010.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest progress ring. version, type, metric.value, and a11y.alt are required. Format, cap, and sweep can be omitted. The center is the share, the cap is round, and the sweep is the full circle.
{
"version": "1",
"type": "progress-ring",
"metric": {
"label": "Done",
"value": 3,
"min": 0,
"max": 8
},
"a11y": {
"alt": "3 of 8 items are done."
}
}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 progress-ring specs. Uptime is the core example, formatted as a percent. Checks closed prints the count, 7 of 10, at 240 by 240. Activity draws three rings at 460 by 320. A size in the spec wins over the preview default.
Center
Omit metric.format and the center is the share of the range, printed as a percent. That is the smallest ring: 3 of 8 reads as 37.5%. Set a format and the center is the value. Uptime's object keeps the one decimal and the percent suffix. Checks closed keeps the integer 7.
Share removes the format. Value puts that example's format back. An example that omitted it gets "number". Activity's rings carry their own labels, so the center figure stays hidden either way. The key still changes.
{
"metric": {
"format": { "style": "number", "decimals": 1, "suffix": "%" }
}
}Cap
mark.linecap is the end of the track and the progress arc. Omit it, or set round, and the ends are round. That is the progress-ring default. A gauge defaults to butt instead. butt is flat. square extends the stroke.
Round removes the key, so the default stays omitted. mark.strokeWidth is the thickness in pixels. Omit it and the ring picks a width that fits. Set it in the playground.
{
"mark": { "linecap": "butt" }
}Sweep
mark.startAngle and mark.endAngle are the track, in degrees. 0 is the top. Positive degrees run clockwise. Omit both and the ring is a full circle, 0° to 360°.
Open sets 0° to 270°, so a quarter of the track stays empty. The arc still starts at the top. This is still type: "progress-ring". It does not grow a needle. Any other pair leaves the buttons unpressed.
{
"mark": { "startAngle": 0, "endAngle": 270 }
}Rings
mark.rings replaces the single arc with concentric rings. Each item is one goal. value is the progress. max defaults to 1. color is the stroke. label is drawn under the stack, with the value. The first item is the outside ring.
Activity is the example that sets this list: move, exercise, and stand. Uptime and Checks closed are one metric, so they omit mark.rings. The demo does not invent rings on those charts. A single value stays a single ring. Copy the list below, or switch to Activity, when you want more than one goal.
{
"mark": {
"rings": [
{ "value": 530, "max": 600, "color": "#ff375f", "label": "Move" },
{ "value": 32, "max": 45, "color": "#30d158", "label": "Exercise" },
{ "value": 10, "max": 12, "color": "#0a84ff", "label": "Stand" }
]
}
}Tooltip
The center, or the ring labels, already state the value. 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 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 progress ring does not use a legend. One ring has a caption. Several rings label themselves. mark.strokeWidth and theme presets live on the playground, with the full option list.