Chart and plot widgets

Two kinds of chart blocks exist:

Typed fences (plot, bars, numberline, plane, timeline) draw an exact picture you can step through and annotate. They follow the shared rules for steps, meta strings, playback, and validation.
Dashboard blocks (kiwi-chart, kiwi-progress) draw a standard chart from rows of data. kiwi-chart can pull its rows from a DQL query, so the chart stays current as pages change.

plot

An x-y plot: complexity curves, latency against load, convergence, the predicate curve of a binary search. A series takes points, or an expr formula in x whose free names come from bind, which can change per step to sweep a parameter. A bare plot fence renders when its body has series. Also spelled kiwi-plot, widget:plot, chart-xy.

```plot id=predicate caption="Binary search on the answer: the predicate flips once"
xLabel: capacity
yLabel: days needed
series:
  - label: days(capacity)
    points: [{x: 10, y: 15}, {x: 15, y: 10}, {x: 20, y: 7}, {x: 25, y: 6}, {x: 30, y: 5}]
guides:
  - {y: 7, label: "budget"}
steps:
  - note: "Too slow: 15 days exceeds the 7-day budget"
    marks: [{x: 10, y: 15, label: "lo"}]
  - note: "Fast enough — search left for a smaller capacity"
    marks: [{x: 20, y: 7, label: "mid"}]
  - note: "The smallest capacity that fits the budget is 20"
    marks: [{x: 20, y: 7, label: "answer"}]
    breakpoint: true
```

All 25 keys

Key	Type	Description
`series`	array of object	Required. `{id?, label?, points: [{x, y}, …], kind?: "line"\|"area"\|"scatter", color?, baseline?}`, or `{expr: "sin(x) + a", samples?, domain?}` for a curve from a formula.
`activeColor`	string	Primary highlight color. Fixed across steps.
`activeIds`	array or number or string	Series ids drawn in the active color.
`ariaLabel`	string	Accessible name. Defaults to a summary derived from the data. Fixed across steps.
`bind`	object	Values for the free names in an `expr` or a `when`, e.g. `{a: 2}`. Steppable, so a walkthrough can sweep a parameter.
`dimIds`	array or number or string	Dimmed series ids.
`guides`	array of object	Reference lines: `{x?, y?, label?, color?}` — an SLO, a threshold, a crossover.
`height`	number	Canvas height, px. Fixed across steps.
`highlightColor`	string	Secondary highlight color. Fixed across steps.
`highlightIds`	array or number or string	Secondary-highlighted series ids.
`marks`	array of object	Single annotated points: `{x, y?, label?, color?}`.
`props`	any	Escape hatch for a widget prop whose name collides with a reserved key.
`regions`	array of object	Shaded areas from a predicate: `{when: "y < x^2", label?, color?, opacity?, resolution?}`. `x` and `y` are in scope.
`shades`	array of object	Shaded bands: `{from, to, series?, fromY?, toY?, color?, label?}`.
`showAxes`	boolean	Draw the axes and frame. Default true. Fixed across steps.
`showLegend`	boolean	Draw the legend. Default true. Fixed across steps.
`width`	number	Canvas width, px. Fixed across steps.
`xLabel`	string	Caption under the x axis. Fixed across steps.
`xMax`	number	Right edge of the x axis.
`xMin`	number	Left edge of the x axis. Defaults to the data extent.
`xTicks`	array of number	Explicit x tick values.
`yLabel`	string	Caption beside the y axis. Fixed across steps.
`yMax`	number	Top of the y axis.
`yMin`	number	Bottom of the y axis.
`yTicks`	array of number	Explicit y tick values.

bars

Columns in value space: histograms, latency distributions, sorting passes. guides draws horizontal reference lines such as an SLO, and overlays draws value-space rectangles such as trapped water or a chosen rectangle. A bare bars fence renders when its body has values. Also spelled kiwi-bars, widget:bars, histogram, barchart.

```bars id=rain caption="Trapping rain water"
values: [0, 1, 0, 2, 1, 0, 1, 3, 2, 1, 2, 1]
steps:
  - note: "Water sits wherever both sides are higher"
    overlays: [{startIndex: 2, toValue: 1, label: "1"}]
    activeIndices: [1, 3]
  - note: "The big basin between 3 and 7 holds four units"
    overlays:
      - {startIndex: 2, toValue: 1}
      - {startIndex: 4, endIndex: 6, toValue: 2, label: "4"}
    activeIndices: [3, 7]
  - note: "Total: 6"
    overlays:
      - {startIndex: 2, toValue: 1}
      - {startIndex: 4, endIndex: 6, toValue: 2}
      - {startIndex: 9, toValue: 2, label: "1"}
```

All 19 keys

Key	Type	Description
`values`	array of number	Required. Bar heights. Negatives draw below a zero baseline.
`activeColor`	string	Primary highlight color. Fixed across steps.
`activeIndices`	array or number or string	Emphasised columns.
`ariaLabel`	string	Accessible name. Defaults to a summary derived from the data. Fixed across steps.
`barColors`	array	Per-bar fill override.
`barWidth`	number	Bar width, px. Default 40. Fixed across steps.
`chartHeight`	number	Plot height, px. Default 220. Fixed across steps.
`dimIndices`	array or number or string	Dimmed or eliminated columns.
`gap`	number	Gap between bars, px. Default 10. Fixed across steps.
`guides`	array of object	Horizontal reference lines: `{value, label?, color?}` — a water level, an SLO.
`highlightColor`	string	Secondary highlight color. Fixed across steps.
`highlightIndices`	array or number or string	Secondary-highlighted columns.
`labels`	array	Labels under each bar. Defaults to the index; `null` hides one.
`maxValue`	number	Top of the value axis.
`minValue`	number	Bottom of the value axis.
`overlays`	array of object	Value-space rectangles: `{startIndex, endIndex?, fromValue?, toValue, label?}` — a water fill, a chosen rectangle.
`pointers`	array of object	Named pointers above columns: `{index, label, color?}`.
`props`	any	Escape hatch for a widget prop whose name collides with a reserved key.
`valueLabels`	boolean or array	Value labels on the bar tips: true (default), false, or custom text per bar.

numberline

A single value axis: inequalities, intervals, thresholds, binary-search buckets. Closed endpoints are filled and open ones hollow. predicate shades wherever a formula in x is true. A bare numberline fence renders when its body has min or max or xRange. Also spelled kiwi-numberline, widget:numberline, number-line, kiwi-number-line.

```numberline id=budget caption="Where this quarter's error budget stands"
label: "% of error budget spent"
min: 0
max: 100
step: 20
intervals:
  - {from: 0, to: 50, label: ship freely}
  - {from: 50, to: 85, label: ship with review}
  - {from: 85, to: 100, label: freeze}
marks: [{at: 85, label: freeze line}]
pointers: [{at: 62, label: now}]
```

All 29 keys

Key	Type	Description
`activeColor`	string	Primary highlight color. Fixed across steps.
`activeIds`	array or number or string	Ids drawn in the active color.
`ariaLabel`	string	Accessible name. Defaults to a summary derived from the data. Fixed across steps.
`dimIds`	array or number or string	Dimmed ids.
`highlightColor`	string	Secondary highlight color. Fixed across steps.
`highlightIds`	array or number or string	Secondary-highlighted ids.
`includeNumbers`	boolean	Print the number under each tick. Default true. Fixed across steps.
`intervals`	array of object	`{from, to, fromOpen?, toOpen?, label?, color?, row?, id?}`. Overlapping intervals stack.
`label`	string	Axis caption. Fixed across steps.
`marks`	array of object	Dashed reference lines: `{at, label?, color?}`.
`max`	number	Right end of the axis. A reversed or empty range is repaired rather than rejected. Fixed across steps.
`min`	number	Left end of the axis. Default 0. Fixed across steps.
`pointers`	array of object	Named pointers above the axis: `{at, label, color?}` — `lo`, `hi`, `mid`.
`points`	array of object	`{x, label?, style?: "closed"\|"open"\|"cross", color?, id?}`.
`predicate`	string	Shade the axis wherever this formula in `x` is true, e.g. `"x^2 < 9"`. Sampled at 400 points.
`predicateColor`	string	Color of the shading. Fixed across steps.
`predicateLabel`	string	Caption over the shaded run.
`props`	any	Escape hatch for a widget prop whose name collides with a reserved key.
`rays`	array of object	`{at, dir: "left"\|"right", open?, label?}` — an inequality with no far end.
`scale`	`linear` \| `log`	Axis scale. `"log"` needs a positive `min`, ticks at powers of ten, and drops values ≤ 0. Fixed across steps.
`selected`	array or number or string	Point or interval ids drawn as selected.
`step`	number	Tick spacing. Omit for automatic nice ticks; a step giving more than 200 ticks falls back to them. Fixed across steps.
`sweep`	number	Position of a sweep cursor.
`sweepLabel`	string	Caption beside the sweep cursor.
`ticks`	array of number	Explicit tick values, overriding `step`.
`why`	any	Point or interval id → explanation, revealed when the reader selects it.
`widgetId`	string	Name for the inspect bus. Fixed across steps.
`width`	number	Canvas width, px. Fixed across steps.
`xRange`	array of number	`[min, max]` or `[min, max, step]`, an alias for the three keys.

plane

A coordinate plane in data units: geometry, sweep lines, convex hulls, vectors, tile maps. It draws what you give it, so the algorithm lives in the steps. Segment and polygon ends can name a point id. A bare plane fence renders when its body has points or segments or polygons or circles or vectors or regions. Also spelled kiwi-plane, widget:plane, geometry.

```plane id=hull caption="Andrew's monotone chain, lower hull"
xMin: 0
xMax: 10
yMin: 0
yMax: 8
points:
  - {id: a, x: 1, y: 1, label: a}
  - {id: b, x: 3, y: 4, label: b}
  - {id: c, x: 5, y: 2, label: c}
  - {id: d, x: 8, y: 6, label: d}
  - {id: e, x: 9, y: 2, label: e}
steps:
  - note: "Sort by x, start the lower hull with a and b"
    polygons: [{points: [a, b], open: true, id: hull}]
    activeIds: [a, b]
  - note: "a→b→c turns clockwise, so b is not on the hull — pop it"
    polygons: [{points: [a, b, c], open: true, id: hull}]
    activeIds: [b]
  - note: "Lower hull is a, c, e"
    polygons: [{points: [a, c, e], open: true, id: hull}]
    highlightIds: [hull]
    dimIds: [b, d]
```

All 31 keys

Key	Type	Description
`activeColor`	string	Primary highlight color. Fixed across steps.
`activeIds`	array or number or string	Ids drawn in the active color.
`ariaLabel`	string	Accessible name. Defaults to a summary derived from the data. Fixed across steps.
`aspect`	`equal` \| `auto`	”equal” (default) keeps circles round and right angles right. Fixed across steps.
`axes`	boolean	Draw the axes through the origin. Default true. Fixed across steps.
`circles`	array of object	`{at, r, label?, dashed?}`.
`dimIds`	array or number or string	Dimmed ids.
`grid`	boolean	Draw the unit grid. Default true. Fixed across steps.
`height`	number	Canvas height, px. Fixed across steps.
`highlightColor`	string	Secondary highlight color. Fixed across steps.
`highlightIds`	array or number or string	Secondary-highlighted ids.
`labels`	array of object	Free text at a position: `{at, text, dx?, dy?}`.
`points`	array of object	`{x, y, id?, label?, style?: "dot"\|"open"\|"cross"\|"square", color?}`. `id` defaults to `pt0`, `pt1`, …
`polygons`	array of object	`{points: [...], label?, open?, fill?}` — a triangle, a hull being built.
`props`	any	Escape hatch for a widget prop whose name collides with a reserved key.
`regions`	array of object	Shaded where a formula holds: `{when: "x + y <= 6", label?, color?, opacity?, resolution?}`. `x` and `y` are in scope; sampled on a grid of at most 60×60.
`segments`	array of object	`{from, to, label?, arrow?, dashed?, color?}`. Each end is a point id, a point index, or a literal `[x, y]`.
`selected`	array or number or string	Point ids drawn as selected.
`sweep`	object	`{axis: "x"\|"y"\|"angle", at, origin?, label?}`.
`vectors`	array of object	`{to, from?, label?}`. `from` defaults to the origin.
`why`	any	Point id → explanation, revealed when the reader selects it.
`widgetId`	string	Name for the inspect bus. Fixed across steps.
`width`	number	Canvas width, px. Fixed across steps.
`xLabel`	string	Caption under the x axis. Fixed across steps.
`xMax`	number	Right edge. Default 10. Fixed across steps.
`xMin`	number	Left edge. Default 0. Fixed across steps.
`xRange`	array of number	`[min, max]`, an alias for xMin/xMax.
`yLabel`	string	Caption beside the y axis. Fixed across steps.
`yMax`	number	Top edge. Default 10. Fixed across steps.
`yMin`	number	Bottom edge. Default 0. Fixed across steps.
`yRange`	array of number	`[min, max]`, an alias for yMin/yMax.

timeline

Spans on a shared axis with named lanes and causal arrows: scheduling, lock handoffs, happens-before, incident timelines. A span with state: blocked or state: waiting draws hatched, so waiting reads differently from working. A bare timeline fence renders when its body has intervals. Also spelled kiwi-timeline, widget:timeline, gantt, schedule.

```timeline id=lock caption="T2 blocks on the row lock T1 holds"
lanes: [T1, T2]
hoverPredecessors: true
intervals:
  - {id: t1run, lane: T1, start: 0, end: 4, label: "UPDATE", state: holding}
  - {id: t1commit, lane: T1, start: 4, end: 5, label: COMMIT, state: running}
  - {id: t2wait, lane: T2, start: 2, end: 5, label: "waiting for lock", state: blocked}
  - {id: t2run, lane: T2, start: 5, end: 8, label: "UPDATE", state: holding}
links:
  - {from: t1commit, to: t2run, label: "lock released"}
steps:
  - note: "T1 takes the row lock"
    activeIds: [t1run]
  - note: "T2's UPDATE blocks — hatched, because it is doing no work"
    activeIds: [t2wait]
  - note: "T1 commits and T2 is woken"
    activeIds: [t1commit, t2run]
```

All 21 keys

Key	Type	Description
`intervals`	array of object	Required. `{start, end, id?, label?, lane?, state?, color?}`. `start === end` draws a point event. `state` of “blocked” or “waiting” draws hatched.
`activeColor`	string	Primary highlight color. Fixed across steps.
`activeIds`	array or number or string	Span ids active this step.
`ariaLabel`	string	Accessible name. Defaults to a summary derived from the data. Fixed across steps.
`dimIds`	array or number or string	Dimmed span ids.
`highlightColor`	string	Secondary highlight color. Fixed across steps.
`highlightIds`	array or number or string	Secondary-highlighted span ids.
`hoverPredecessors`	boolean	Hovering a span lights the happens-before cone behind it. Fixed across steps.
`laneHeight`	number	Row height, px. Default 26. Fixed across steps.
`lanes`	array of string	Named lanes in draw order, labelled in the gutter — `thread A` above `thread B`.
`links`	array of object	Causal arrows between spans: `{from, to, label?, dashed?}` — happens-before, woken by, lock handoff.
`marks`	array of object	Extra vertical marks: query points, event coordinates. `{at, label?, color?}`.
`max`	number	Right end of the axis.
`min`	number	Left end of the axis. Defaults to the data extent.
`props`	any	Escape hatch for a widget prop whose name collides with a reserved key.
`showAxis`	boolean	Draw the axis. Default true. Fixed across steps.
`showLegend`	boolean	Draw a legend for the `state` values in use. Fixed across steps.
`sweep`	number	Position of the sweep cursor.
`sweepLabel`	string	Caption beside the sweep cursor — usually the running counter.
`ticks`	array of number	Values to label on the axis.
`width`	number	Canvas width, px. Fixed across steps.

kiwi-chart

Bar, line, area, pie, radar, and scatter charts from inline rows, rendered with Recharts.

```kiwi-chart
type: bar
title: Weekly deploys
xKey: week
data:
  - week: W40
    deploys: 21
    rollbacks: 2
  - week: W41
    deploys: 34
    rollbacks: 1
  - week: W42
    deploys: 28
    rollbacks: 3
series:
  - key: deploys
    color: "#22c55e"
  - key: rollbacks
    color: "#ef4444"
legend: true
```

Without series, every numeric column in the first row becomes a series. Without xKey, bar, line, and area charts draw no category axis, so name it. To chart live data, give a query: instead of data:. The first non-numeric result column becomes the x axis and every numeric column becomes a series. Inline data still renders if the query fails.

```kiwi-chart
type: bar
title: Open incidents by service
query: |
  TABLE title, open_incidents FROM "services" SORT open_incidents DESC
```

kiwi-chart keys

Key	Type	Description
`type`	`bar` \| `line` \| `area` \| `pie` \| `radar` \| `scatter`	Chart type. Default `bar`.
`title`	string	Heading above the chart.
`data`	array of object	Rows. Required unless `query` is set.
`query`	string	DQL query whose result rows replace `data`. Use a `\|` block for multi-line queries.
`xKey`	string	Column for the category axis. Pie and radar charts fall back to the first text column; scatter to `x`.
`yKey`	string	Scatter only: column for y values.
`series`	array of object	`{key, color?, name?, stackId?}` per plotted column.
`stacked`	boolean	Stack the series.
`legend`	boolean	Show a legend.
`grid`	boolean	Show grid lines.
`height`	number	Chart height in px. Default 300.
`colors`	array of string	Palette for inferred series.

The body can also be JSON with the same keys.

kiwi-progress

Progress bars or radial gauges, one per item.

```kiwi-progress
type: bar
title: Q4 migration
items:
  - label: Backend services
    value: 85
  - label: Web UI
    value: 60
  - label: Data backfill
    value: 3
    max: 12
```

kiwi-progress keys

Key	Type	Description
`type`	`bar` \| `gauge`	Horizontal bars or radial gauges. Default `bar`.
`title`	string	Heading above the items.
`items`	array of object	`{label, value, max?, color?}`. `max` defaults to 100. Without `color`, the fill goes from red to green as the item nears `max`.
`showPercent`	boolean	Show the percentage. Default true.
`animated`	boolean	Animate the fill. Default true.

Widgets overview

Fence names, steps, playback, and validation.

DQL

The query language behind kiwi-chart queries.

Data and queries

kiwi-query, kiwi-data, and kiwi-kanban.

Diagrams

graph, sequence, steps, Mermaid, and D2.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

plot

bars

numberline

plane

timeline

kiwi-chart

kiwi-progress

Widgets overview

DQL

Data and queries

Diagrams

​plot

​bars

​numberline

​plane

​timeline

​kiwi-chart

​kiwi-progress

​Related

Widgets overview

DQL

Data and queries

Diagrams

plot

bars

numberline

plane

timeline

kiwi-chart

kiwi-progress

Related