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, and legend.interactive stay off unless set. Turning them on loads more interaction code.
  • tooltip.fields chooses the rows and their order. A string is a field name. An object sets title and a format preset.
  • tooltip.position is auto, top, bottom, left, or right. tooltip.crosshairLabel prints the hovered x value on the guide.
  • animation.easing and interaction.select warn CK3012. theme.tokens.fontFamily sets 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, and a11y.description are drawn.

Repair loop

ts
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

  • version is "1". a11y.alt is one sentence and is required.
  • data is an array of rows. It is not { "values": [...] }. Large data may use { "columns": { "field": [] } }.
  • type is the chart. mark is options: curve, sampling, stack, layout. Not a string.
  • Gauge, kpi, and progress-ring use metric: value, min, max, delta, label. mark.rings stacks activity rings. encoding.volume draws a pane under candles. metric.thresholds colours a kpi from the value.
  • Donut uses encoding.x for the slice label and encoding.y for the value.
  • A second axis is encoding.*.axis: "y2". Titles go in axes.y2.title.
  • Field types are quantitative, temporal, ordinal, or nominal.
  • A y range is encoding.y.scale.domain: [min, max]. Either end may be null to 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.sampling defaults to auto and downsamples line-like charts above twice the plot width. none draws every point and is much slower at 100k and 1M.

Chart types

TypeWhat it draws
lineA trend across ordered categories. Add area: true on a y channel for a filled line, or dash for a target.
barA comparison across categories. Several y channels stack when mark.stack is stack or percent.
pieParts of a whole with no hole. encoding.x is the slice label and encoding.y is the value.
donutParts of a whole. encoding.x is the slice label and encoding.y is the value. The center shows the total.
stacked-areaSeveral series stacked into one shape. mark.stack percent normalizes each x to 100%.
scatterTwo quantitative fields, with an optional size channel for bubbles.
comboBars and a line in one spec. Put the line on axis y2 when the units differ.
heatmapA grid when x, y, and color are set. A calendar when x is a date and color is the measure.
gaugeA semicircular meter. The number lives in metric, with min, max, and optional bands.
kpiA label, a formatted value, a delta, and an optional sparkline from data.
sparklineA small line with no axes. data can be a plain number array.
mini-areaA small filled trend, also happy with a number array.
progress-ringA circular share of metric.max. The value is metric.value, not a data column.
spikeThin marks for bursts over time. A quiet baseline makes the spike readable.
candlestickOpen, high, low, and close. Optional volume.
histogramBins one quantitative field. mark.bins sets the count.
boxplotQuartiles, whiskers, a median, and outlier dots for each category.
radarOne polygon per series around a shared set of spokes.
funnelStages in data order, width proportional to the value.
treemapArea tiles. encoding.color groups them.
sankeyFlows from a source field to a target field.
bulletA value against a target and qualitative ranges.
waterfallSigned steps between totals.
area-rangeA band between a low and a high, with an optional centre line.
bar-rangeA floating bar from a low value to a high value.
errorbarWhiskers on a point or a bar.
ganttTasks as bars on a time axis, with sections, milestones, and dependencies.
timelineEvents on a date axis, with eras as spans.
quadrantPoints on a square split into four labeled regions.
vennTwo or three sets. Two are area-proportional. Three are approximate.
journeySections and steps, with a 1–5 score and actor chips.
radial-barCategories around a circle. Length is the radius. Series sit side by side unless they stack outward.
roseEqual angles, with the radius as the value. Polar area and nightingale use this type.
streamgraphStacked areas around a moving baseline. The baseline is not zero.
treeA tidy node-link layout of one hierarchy. Cluster lines the leaves up.
densityA 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.