Spec reference
The schema is chartkit.dev/schema/v1.json. validate() checks the schema and the data. render() does not validate. Unknown types return an error SVG and do not throw.
Client runtime
Tooltip, zoom, pan, brush, and animation duration run in @chartkitdev/core/interact. The static SVG records those choices in data-ck-intent and does not paint the controls.
- Tooltip defaults on for line, bar, area, scatter, combo, and donut.
a11y.keyboard,a11y.dataTable, andlegend.interactivestay off unless set. Turning them on loads more interaction code.tooltip.fieldschooses the rows and their order. A string is a field name. An object setstitleand aformatpreset.tooltip.positionisauto,top,bottom,left, orright.tooltip.crosshairLabelprints the hovered x value on the guide.animation.easingandinteraction.selectwarn CK3012.theme.tokens.fontFamilysets the family. Omitted, the chart inherits the page font. A bad family is CK3086.- Axis titles, tick counts, rotation, side, reversed scales,
nice: false, padding, min height, anda11y.descriptionare drawn.
Repair loop
import { repair, validate } from "@chartkitdev/core/validate";
import { render } from "@chartkitdev/core/all";
const result = validate(spec);
if (!result.ok) {
const fixed = repair(spec);
if (fixed.ok) render(fixed.spec);
}repair applies the safe JSON Patch on each error and returns { spec, ok, errors, applied }. The input is not mutated. It does not invent data. A missing or unknown type is reported first.
Rules
versionis"1".a11y.altis one sentence and is required.datais an array of rows. It is not{ "values": [...] }. Large data may use{ "columns": { "field": [] } }.typeis the chart.markis options: curve, sampling, stack, layout. Not a string.- Gauge, kpi, and progress-ring use
metric: value, min, max, delta, label.mark.ringsstacks activity rings.encoding.volumedraws a pane under candles.metric.thresholdscolours a kpi from the value. - Donut uses
encoding.xfor the slice label andencoding.yfor the value. - A second axis is
encoding.*.axis: "y2". Titles go inaxes.y2.title. - Field types are quantitative, temporal, ordinal, or nominal.
- A y range is
encoding.y.scale.domain:[min, max]. Either end may benullto stay automatic, as in[0, null]. A y2 channel uses the same domain for the combo's second axis. Ticks stay inside that range, and points outside it are clipped to the plot. mark.samplingdefaults toautoand downsamples line-like charts above twice the plot width.nonedraws every point and is much slower at 100k and 1M.
Chart types
| Type | What it draws |
|---|---|
| line | A trend across ordered categories. Add area: true on a y channel for a filled line, or dash for a target. |
| bar | A comparison across categories. Several y channels stack when mark.stack is stack or percent. |
| pie | Parts of a whole with no hole. encoding.x is the slice label and encoding.y is the value. |
| donut | Parts of a whole. encoding.x is the slice label and encoding.y is the value. The center shows the total. |
| stacked-area | Several series stacked into one shape. mark.stack percent normalizes each x to 100%. |
| scatter | Two quantitative fields, with an optional size channel for bubbles. |
| combo | Bars and a line in one spec. Put the line on axis y2 when the units differ. |
| heatmap | A grid when x, y, and color are set. A calendar when x is a date and color is the measure. |
| gauge | A semicircular meter. The number lives in metric, with min, max, and optional bands. |
| kpi | A label, a formatted value, a delta, and an optional sparkline from data. |
| sparkline | A small line with no axes. data can be a plain number array. |
| mini-area | A small filled trend, also happy with a number array. |
| progress-ring | A circular share of metric.max. The value is metric.value, not a data column. |
| spike | Thin marks for bursts over time. A quiet baseline makes the spike readable. |
| candlestick | Open, high, low, and close. Optional volume. |
| histogram | Bins one quantitative field. mark.bins sets the count. |
| boxplot | Quartiles, whiskers, a median, and outlier dots for each category. |
| radar | One polygon per series around a shared set of spokes. |
| funnel | Stages in data order, width proportional to the value. |
| treemap | Area tiles. encoding.color groups them. |
| sankey | Flows from a source field to a target field. |
| bullet | A value against a target and qualitative ranges. |
| waterfall | Signed steps between totals. |
| area-range | A band between a low and a high, with an optional centre line. |
| bar-range | A floating bar from a low value to a high value. |
| errorbar | Whiskers on a point or a bar. |
| gantt | Tasks as bars on a time axis, with sections, milestones, and dependencies. |
| timeline | Events on a date axis, with eras as spans. |
| quadrant | Points on a square split into four labeled regions. |
| venn | Two or three sets. Two are area-proportional. Three are approximate. |
| journey | Sections and steps, with a 1–5 score and actor chips. |
| radial-bar | Categories around a circle. Length is the radius. Series sit side by side unless they stack outward. |
| rose | Equal angles, with the radius as the value. Polar area and nightingale use this type. |
| streamgraph | Stacked areas around a moving baseline. The baseline is not zero. |
| tree | A tidy node-link layout of one hierarchy. Cluster lines the leaves up. |
| density | A kernel density curve of a quantitative sample. Groups overlay. |
Spec anatomy is the short version of the required keys. Each type’s page is linked above, and the gallery is the catalog.