Tile types

A tile is one entry in the spec's tiles array. Every tile carries a type, and that type decides which other fields are required. A build guard reads the published schema and fails this site when a tile type exists with no row here or when a row's required bindings disagree with the schema.

Every tile also accepts w (an integer 1 to 12, its width in grid columns). All of them except text and custom accept dataset, which routes the tile at a named dataset; custom names its datasets with reads instead, and text reads none.

The eighteen types

Type	Required bindings	What it draws
kpi	measure	One number, with an optional drill-through.
chart	chart, x	Bar, horizontal bar, line or area.
table	none	The dataset as a table.
matrix	rows, cols, measure	A cross-tab with real subtotals.
heatmap	rows, cols, measure	The matrix, colour-scaled.
scatter	point, x_measure, y_measure	Two measures against each other, one point per member.
treemap	x, measure	Part-of-whole by rectangle area.
waterfall	x, measure	A total broken into the contributions that make it up.
funnel	x, measure, stages	Declared stages in declared order, with step conversion.
drilldown	levels, measure	A breakdown you can descend, one level per click.
stacked	x, series, measure	Stacked bars or areas, normal or 100 percent.
combo	x, measure, measure2	Two measures on two axes.
pie	x, measure	Share of a whole.
donut	x, measure	The same, with the total in the hole.
gauge	measure, max	One measure against a declared scale.
filter	dimension	A slicer over one dimension.
text	body	Markdown prose. Reads no data.
custom	reads	Your own HTML, your own JavaScript, or both.

pie and donut are two values of one schema shape, which is why they take the same bindings.

Optional bindings, by tile

Type	Also accepts
kpi	drill, title, note, intent
chart	measure or measures (2 to 4), series, sort, limit (1 to 100), height (120 to 800), cross_filter, viewer, drill
table	columns (1 to 12), group, sort, limit (1 to 500), viewer, drill
matrix	subtotals, limit (1 to 1,000), color
heatmap	subtotals, limit (1 to 1,000), color
scatter	limit (1 to 2,000), height, drill
treemap	limit (1 to 200), height, drill
waterfall	limit (1 to 200), height, drill
funnel	height, drill
drilldown	top_n (1 to 1,000), other, total
stacked	stack, chart, limit (1 to 400), height
combo	chart, chart2, axis_sync, limit (1 to 400), height
pie, donut	height
gauge	min, target, height
filter	label, multi, range
text	nothing beyond body, intent and w
custom	html, js, title, note

title and note are accepted on every tile except filter and text. intent is accepted on all eighteen and is never rendered.

A chart takes exactly one of measure or measures. measures (2 to 4 keys) draws a multi-series chart and forbids series. cross_filter: true restricts the chart to bar or hbar and forbids both series and measures. viewer (any of sort, limit) adds live controls and is refused alongside measures or series.

A filter takes at most one of multi and range, never both.

A custom tile needs at least one of html (up to 100,000 characters) or js (up to 200,000 characters). Its reads array names 1 to 8 datasets, and the runtime hands the tile exactly those. The published page runs in a sandboxed opaque origin, so browser storage and cookies are unavailable to it, though cross-origin fetch is not blocked. See what a tile cannot do.

Honest degradation

The rule these tiles follow is that a tile that cannot be exact says so, in place, with the reason. It never renders a plausible wrong picture, and it never silently drops the part it could not compute.

Type	What it does when it cannot be exact
treemap	The rectangles are laid out against the dataset's own total, never against the sum of the rectangles. If a limit truncates the members, or a member cannot be resolved, the rest of the box stays empty rather than being renormalized to fill it. It refuses outright on a measure that does not decompose, on a negative value, and when the dataset reports no positive total.
waterfall	Every step is positioned where the previous one ended, so one missing contribution moves all of them. The whole chart is withheld rather than drawn with a step that would read as "no change". It also refuses when the dataset reports no total, and when the contributions do not reconcile with it.
stacked	A negative segment means a stacked bar's length would stop being the sum of its parts, so the same exact values are drawn grouped instead, with a line saying why. A 100 percent stack whose column mixes signs, or whose column totals zero, is withheld: no share of it would be a true proportion.
pie, donut	Refused on a measure whose parts do not compose to its whole, on a negative slice, when the slices add up to more than the dataset's own total, and past five slices (the width of the validated mark palette). When the slices do not account for the whole, that is disclosed rather than hidden.
matrix, heatmap	A subtotal is re-evaluated by the resolver, never summed from the children on screen. A cell the dataset cannot resolve renders as unavailable and is never coloured as though it were a value.
drilldown	An Other residual row is composed by the resolver from the members not shown. Where the measure cannot be recombined across those members, the Other row renders as unavailable with the reason, and the members that are shown keep their exact values.
chart, table, kpi	A binding the dataset cannot answer under the current filters renders as unavailable with the reason, in place of the figure.

Every one of those refusals is a runtime behaviour on the published page, under whatever filters the reader has applied. They are separate from the publish-time refusals, which stop a wrong dashboard existing at all: see Errors.

Where a tile truncates

Some tiles cap how much they render even when you set no limit. Past the cap they truncate and disclose it on the tile.

Type	Default before truncation	Ceiling you can raise it to
matrix, heatmap	200 rows, 100 columns	1,000 rows via limit
scatter	500 points	2,000 via limit
treemap	24 rectangles	200 via limit
waterfall	40 contribution bars	200 via limit
drilldown	200 members per level	not raisable, see below
stacked, combo	60 x-axis positions	400 via limit
pie, donut	5 slices, and this is a hard refusal rather than a truncation	not raisable

top_n on a drilldown only ever cuts. The schema accepts a top_n up to 1,000, but the renderer clamps the members it draws to 200 regardless, so a top_n above 200 changes nothing. Use it to show a Top 10 with an Other residual, not to widen a level.

Check it worked

Publish with dry_run: true and read the warnings. Several tiles carry publish-time checks that fire before the page exists: a funnel stage that no dimension member matches, a stacked chart over a measure that does not add up, a series dimension whose cardinality is past the palette. Fixing those at publish is cheaper than discovering the tile withheld itself in front of a reader.