Report Chart Reference

🧪 Experimental feature (preview). This feature is under active development and released early so you can try it and give feedback. Behaviour, options, and results can change without notice, and it isn’t covered by the usual support and stability guarantees. Avoid relying on it for production work.

Overview

A Report chart tile names a chartType and a handful of columns. Between your JSON and the chart primitive that draws it sits an adapter: a small piece of data shaping that groups, rolls up, buckets or pivots the page’s records into the shape that primitive wants. Which adapter runs — and therefore which fields the tile reads — is decided by the chart’s family.

This page is the reference for that layer. For the envelope around a tile (size, palette, theme, filter, the list and hosted tiles), see Writing Report Definitions. For which chart to choose given a set of columns, see Designing a Report from Data.

Two facts shape everything below:

• Every tile is 300 px tall. A chart has to read at that size. Fewer categories and shorter labels always win.
• Aggregation happens at render time from the records on the page. You choose columns and a method; you never write values. Text that looks like a number is treated as a number; a cell that’s empty groups under (none).

How a chart gets its data

Ten adapters feed the 36 chart types. Knowing what they do explains most surprises.

Categorical roll-up

Feeds: bar, horizontalBar, lollipop, pareto, pie, donut, treemap, funnel, waterfall, line, area, sparkline, figure, gauge, bullet.

Groups the records by dimension and rolls up measure with aggregation:

• count — rows per group. measure is ignored (write "").
• sum — the total of measure per group. Non-numeric cells count as 0.
• avg — the mean of measure per group.

Values are rounded to two decimals. Groups are sorted largest first and capped at 8: the top 7 keep their names and everything else is lumped into one Other bucket (for avg, Other is the mean of the lumped means). Empty cells group as (none).

Two consequences matter. A dimension with dozens of values still renders — as seven bars and a big Other — so pick dimensions with 2–12 distinct values. And the order is by value, never by your data’s order, which is why the line, area and funnel charts in this family don’t preserve a sequence (see each chart below).

Pivot

Feeds: groupedBar, stackedBar, radar, heatmap, sunburst.

A two-way table: dimension values become the categories (most frequent first, capped at 12), seriesField values become the series (most frequent first, capped at 8), and each cell is the roll-up of measure by aggregation for that pair. Both columns should be categoricals with a handful of values each; a 12 × 8 heatmap is the most a 300 px tile will show legibly.

Time buckets

Feeds: timeSeries, timeBar, cumulative, burndown, calendar.

Parses dimension as a date, buckets every row into the calendar period named by granularity (day, week, month, quarter, year), rolls up measure by aggregation per period, and returns the periods in chronological order. Rows whose date won’t parse are skipped.

• Empty periods between the first and last are filled with zero so gaps read as gaps (not for avg, where a zero mean would be a lie). At most 400 periods are shown; a day-grained span of many years keeps only the latest 400.
• Date parsing handles ISO (2026-03-01), slash and dash dates, epoch numbers, and anything the browser parses. Day-first versus month-first is detected from the whole column (a component over 12 settles it), so 1/6/2026 is read consistently for the data rather than always as January 6th.
• Labels follow the grain: Aug 5, Aug 2026, 2026-Q3, 2026.

Weeks start on Monday. cumulative replaces each period’s value with the running total to that point.

Flow stages

Feeds: sankey, network, flow.

Reads stageFields, an ordered list of at least two columns. Each record threads through every stage in order, and links are aggregated between every consecutive pair (stage 0 → 1, 1 → 2, …), weighted by measure/aggregation. Nodes are scoped to their stage, so the value "Open" in stage 1 and "Open" in stage 3 are two different nodes and the graph stays a clean left-to-right flow. Zero-weight links are dropped; at most 120 links are kept. With stageFields absent, the adapter uses [dimension, seriesField] as a two-stage flow.

XY points

Feeds: scatter, bubble.

One point per record: xMeasure and yMeasure (and sizeMeasure for bubbles) read as numbers; rows where either won’t parse are skipped. No aggregation. An optional seriesField colours the points by group, up to 8 groups.

Box statistics

Feeds: boxplot.

Groups measure values by dimension and computes min, lower quartile, median, upper quartile and max per group, for up to 12 groups. No aggregation; needs several rows per group to mean anything.

Histogram values

Feeds: histogram.

Collects every numeric value of measure across all rows — no dimension, no aggregation — and the primitive bins them into equal-width bins spanning the observed range.

Daily OHLC

Feeds: candlestick.

Groups rows by the calendar day of dimension, and for each day takes measure’s first value as open, last as close (in the order the records arrive), and the day’s extremes as high and low. No aggregation. Days are ordered chronologically.

Spans

Feeds: gantt.

One bar per record from startField to endField (both parsed as days; rows missing either are skipped; an end before its start is swapped). labelField names the row, falling back to #1, #2, …; seriesField colours bars by group. At most 60 spans, sorted by start.

Families at a glance

Fields a family doesn’t read are ignored, not rejected. Setting only what’s needed keeps a definition honest about what drives each chart.

Chart by chart

Grouped the way the picker groups them. “Best with” describes the data shape that makes the chart worth looking at. Palette group: categorical means distinct hues for unordered categories (ember, tableau, slate, earthen); sequential means a continuous ramp for magnitude or order (viridis, inferno, magma, plasma, cividis, turbo, warm, cool, spectral). See Palettes.

Compare

Composition

Trend

Time

Distribution

Relationship

Single value

Legends and orientation

orientation (left / right) and showLegend: false don’t apply to every chart. What they do depends on the primitive:

Omit showLegend for the default (shown). A legend hidden on a bar chart is often the better small-tile choice: the axis labels are right under the bars.

Palettes

Thirteen palettes in two groups. Match the group to what the colour encodes.

Categorical — distinct hues for unordered categories. Eight swatches each, cycling when a chart needs more.

Sequential — a continuous ramp sampled evenly across however many values the chart has (a single value takes the midpoint). They encode magnitude or order.

Which group for which chart. Sequential for heatmap, calendar, gauge, figure, waterfall, burndown, the time family, and a treemap sized by a measure. Categorical for everything that names discrete groups: bar, horizontalBar, lollipop, pareto, pie, donut, sunburst, funnel, groupedBar, stackedBar, radar, sankey, network, flow, scatter, bubble, boxplot, bullet, gantt, and the list tile. Any palette renders on any chart — the group is about whether the colours say something true.

Keep a report to one categorical palette and one sequential palette. A different palette per tile reads as noise. On the dark canvas themes, the brighter categorical sets (tableau, ember) and the high-contrast ramps (viridis, plasma, turbo) hold up best; earthen and slate suit the light themes.

The tile’s accent bar (the coloured strip along the top of the card) is the palette’s first colour, so palette choice also colours the chrome.

Defaults and self-healing

When data arrives, each tile checks that the columns it needs exist and quietly fills any that don’t:

A column whose name is id, key, guid, or ends in .id / .guid is treated as a surrogate key and never auto-picked as a measure or axis. You can still name one explicitly; you shouldn’t.

Self-healing exists so a freshly added tile shows something. It’s not a substitute for naming the columns you mean — an auto-picked dimension may be the least interesting column in the data.