chart

A chart of a list of records: bar or line for one or more numbers per item, such as revenue and last year's revenue by month, stacked for each item's total split into parts, such as revenue by product per month, area for an amount over time, hbar for a ranking with long names, such as top customers, pie or donut for how one number splits across items, such as sales by region, funnel for how many get through each stage, such as leads to won deals, waterfall for how changes add up to a total, such as revenue minus costs, bullet for each KPI against its target, such as quarterly goals, heatmap for one number across two dimensions, such as retention by cohort, scatter for how two numbers relate, such as price against rating, treemap for how a total splits across many parts, such as costs by line item, or sankey for how amounts flow from sources to where they end up, such as budget to departments to projects. It redraws when the list changes, and shows at most 200 items, 6 series and 6 slices (smaller slices are summed into Other).

Spec · edit me

No problems. The parser accepted every line.

Result · try itOpen in playground

Tweak the props"text"

kind

labels

good

total

format

Props

"text"textA title above the chart.optional

kindbar · hbar · line · area · stacked · pie · donut · funnel · waterfall · bullet · heatmap · scatter · treemap · sankeybar compares categories and always starts at 0; hbar draws the bars across, one row per item with its name on the left and its value at the end, for rankings and long names (top 10 artists or customers): sort the list and take() the top items, since rows are drawn in list order; line shows a trend in list order, scaled to the values; area is a line with the space under it filled down to 0, for amounts over time such as visitors a week; stacked piles each item's y fields into one bar, bottom up in the order written, with its total on top, for parts of a whole such as revenue by product per month; pie and donut show each item's share of the total, and donut puts the total in the middle; funnel shows stages top to bottom in list order, each with its share of the stage before; waterfall shows each item as a change from the running total, rises good and falls bad, with total= adding the final total as a last bar; bullet gives each item a row with its bar against the goal in target=, colored good when on target, warn when close and bad when far off, each row on its own scale so mixed units fit, at most 20 rows; heatmap draws a grid with a row per value of rows= and a column per value of x=, each cell shaded by its y number (darker is more), for patterns such as orders by weekday and hour; scatter puts a dot per item at its x and y numbers, both on number scales, with label= naming each dot, size= sizing it by a number and group= coloring it by category (at most 6), and labels= naming the axes, e.g. labels="Risk,Return"; treemap splits a rectangle into one per item, its area its share of the total, biggest top left in the strongest color, with names where they fit, for when there are too many parts for a pie (up to 60; the smallest are drawn together as one). sankey draws bands between columns of places, each as thick as its amount, from one flow per item: from= and to= name the places and y= the amount; columns are worked out from the flows, and flows that go round in a circle show a message (at most 40 places and 120 flows). pie, donut, funnel, waterfall, bullet, heatmap, scatter, treemap and sankey take one y field; pie, donut, funnel, bullet, treemap and sankey take no negative values.bar

itemsexpressionThe list of records to chart, e.g. items=sales or items={filter(sales, 'open')}.required

xnameThe field holding each item's label (each slice's name in a pie), e.g. x=month. For scatter, the field with each item's x number. Not used by sankey.required

ynamesThe field holding each item's number, e.g. y=revenue. Bar, hbar and line can compare up to 6 fields on one scale, separated by commas with no spaces, e.g. y=revenue,last_year; each gets its own color and a legend. stacked and area take up to 6 fields too. Items without a number are shown as gaps, not zero.required

labelsstringBar, hbar, line, area and stacked with several y fields: the legend's names, in the same order, separated by commas, e.g. labels="This year,Last year". Without it the legend shows the field names. Scatter: the two axes' names, x then y, e.g. labels="Risk,Return".—

labelnameScatter only: the field naming each dot, shown in its tip and the data table, e.g. label=name.—

sizenameScatter only: the field whose number sizes each dot (its area), for bubbles, e.g. size=assets.—

groupnameScatter only: the field whose category colors each dot, with a legend, at most 6, e.g. group=type.—

fromnameSankey only: the field naming where each flow starts, e.g. from=source.—

tonameSankey only: the field naming where each flow goes, e.g. to=target.—

rowsnameHeatmap only: the field holding each item's row, e.g. rows=day; x= holds its column and y= its number.—

targetnameBullet only: the field holding each item's goal, drawn as a dark tick across its bar, e.g. target=goal.—

goodup · downBullet only: up when reaching or passing the target is good (sales, signups), down when staying under it is (costs, churn, response time).up

totalstringWaterfall only: the name of an extra last bar showing the total the changes add up to, e.g. total="Net income".—

formatnumber · money · percentHow values read on the axis, at the ends of hbar bars, in a pie's legend and in a donut's middle: number (37K), money ($37K) or percent (42%), for values that are already percentages, like a rate of 42 or a retention of 61.5. On a scatter it formats y only; x reads as a plain number.number

ifconditionShow only when this expression is true, e.g. if=done or if={count>0}. Every element takes it.—

tipstringA short explanation shown on hover, keyboard focus or a tap, e.g. tip="Orders not yet shipped": for a term or a number some people won't know, instead of more words on screen. It makes the element a Tab stop if it isn't one. Every element takes it.—

Children: chart-linechart-rulechart-note

For your model

The exact guide entry a model gets for chart, generated from the same definition.

  chart "<text>"  — A chart of a list of records: bar or line for one or more numbers per item, such as revenue and last year's revenue by month, stacked for each item's total split into parts, such as revenue by product per month, area for an amount over time, hbar for a ranking with long names, such as top customers, pie or donut for how one number splits across items, such as sales by region, funnel for how many get through each stage, such as leads to won deals, waterfall for how changes add up to a total, such as revenue minus costs, bullet for each KPI against its target, such as quarterly goals, heatmap for one number across two dimensions, such as retention by cohort, scatter for how two numbers relate, such as price against rating, treemap for how a total splits across many parts, such as costs by line item, or sankey for how amounts flow from sources to where they end up, such as budget to departments to projects. It redraws when the list changes, and shows at most 200 items, 6 series and 6 slices (smaller slices are summed into Other).
    "<text>"  A title above the chart.
    kind=<bar|hbar|line|area|stacked|pie|donut|funnel|waterfall|bullet|heatmap|scatter|treemap|sankey>  bar compares categories and always starts at 0; hbar draws the bars across, one row per item with its name on the left and its value at the end, for rankings and long names (top 10 artists or customers): sort the list and take() the top items, since rows are drawn in list order; line shows a trend in list order, scaled to the values; area is a line with the space under it filled down to 0, for amounts over time such as visitors a week; stacked piles each item's y fields into one bar, bottom up in the order written, with its total on top, for parts of a whole such as revenue by product per month; pie and donut show each item's share of the total, and donut puts the total in the middle; funnel shows stages top to bottom in list order, each with its share of the stage before; waterfall shows each item as a change from the running total, rises good and falls bad, with total= adding the final total as a last bar; bullet gives each item a row with its bar against the goal in target=, colored good when on target, warn when close and bad when far off, each row on its own scale so mixed units fit, at most 20 rows; heatmap draws a grid with a row per value of rows= and a column per value of x=, each cell shaded by its y number (darker is more), for patterns such as orders by weekday and hour; scatter puts a dot per item at its x and y numbers, both on number scales, with label= naming each dot, size= sizing it by a number and group= coloring it by category (at most 6), and labels= naming the axes, e.g. labels="Risk,Return"; treemap splits a rectangle into one per item, its area its share of the total, biggest top left in the strongest color, with names where they fit, for when there are too many parts for a pie (up to 60; the smallest are drawn together as one). sankey draws bands between columns of places, each as thick as its amount, from one flow per item: from= and to= name the places and y= the amount; columns are worked out from the flows, and flows that go round in a circle show a message (at most 40 places and 120 flows). pie, donut, funnel, waterfall, bullet, heatmap, scatter, treemap and sankey take one y field; pie, donut, funnel, bullet, treemap and sankey take no negative values.
    items=<expression, required>  The list of records to chart, e.g. items=sales or items={filter(sales, 'open')}.
    x=<name, required>  The field holding each item's label (each slice's name in a pie), e.g. x=month. For scatter, the field with each item's x number. Not used by sankey.
    y=<names, required>  The field holding each item's number, e.g. y=revenue. Bar, hbar and line can compare up to 6 fields on one scale, separated by commas with no spaces, e.g. y=revenue,last_year; each gets its own color and a legend. stacked and area take up to 6 fields too. Items without a number are shown as gaps, not zero.
    labels=<string>  Bar, hbar, line, area and stacked with several y fields: the legend's names, in the same order, separated by commas, e.g. labels="This year,Last year". Without it the legend shows the field names. Scatter: the two axes' names, x then y, e.g. labels="Risk,Return".
    label=<name>  Scatter only: the field naming each dot, shown in its tip and the data table, e.g. label=name.
    size=<name>  Scatter only: the field whose number sizes each dot (its area), for bubbles, e.g. size=assets.
    group=<name>  Scatter only: the field whose category colors each dot, with a legend, at most 6, e.g. group=type.
    from=<name>  Sankey only: the field naming where each flow starts, e.g. from=source.
    to=<name>  Sankey only: the field naming where each flow goes, e.g. to=target.
    rows=<name>  Heatmap only: the field holding each item's row, e.g. rows=day; x= holds its column and y= its number.
    target=<name>  Bullet only: the field holding each item's goal, drawn as a dark tick across its bar, e.g. target=goal.
    good=<up|down>  Bullet only: up when reaching or passing the target is good (sales, signups), down when staying under it is (costs, churn, response time).
    total=<string>  Waterfall only: the name of an extra last bar showing the total the changes add up to, e.g. total="Net income".
    format=<number|money|percent>  How values read on the axis, at the ends of hbar bars, in a pie's legend and in a donut's middle: number (37K), money ($37K) or percent (42%), for values that are already percentages, like a rate of 42 or a retention of 61.5. On a scatter it formats y only; x reads as a plain number.
    children: chart-line, chart-rule, chart-note
    example:
      state sales=[{month: "Jan", revenue: 12000, last_year: 10000}, {month: "Feb", revenue: 18000, last_year: 14000}, {month: "Mar", revenue: 15000, last_year: 16000}]
      chart "Revenue vs last year" kind=line items=sales x=month y=revenue,last_year labels="This year,Last year" format=money

  chart-line "<text>"  — Under a bar or line chart: another field of the same items drawn as a line on top, on the same scale, such as a forecast or last year over this year's bars. Name the chart's own bars in the legend with its labels=, like labels="This year".
    "<text>"  Its name in the legend. Defaults to the field name.
    y=<name, required>  The field holding each item's number, e.g. y=forecast.
    only inside: chart
    example:
      chart-line "Last year" y=last_year

  chart-rule "<text>"  — Under a bar or line chart: a level drawn across the plot, such as a target, a budget or an average.
    "<text>"  What the level is, shown at its end, e.g. "Target".
    y=<expression, required>  The level, a number or a formula, e.g. y=50000 or y={avg(pluck(sales, 'revenue'))}.
    only inside: chart
    example:
      chart-rule "Target" y=16000

  chart-note "<text>"  — Under a bar or line chart: a marker at one item with a few words, such as a launch or an outage.
    "<text>" (required)  The words, kept short, e.g. "Launch".
    at=<string, required>  The item it marks: its x value as shown under the chart, e.g. at="Jun".
    only inside: chart
    example:
      chart-note "Launch" at="Feb"

More data

stat rating chart-line chart-rule chart-note meter table table-column compare compare-row details detail schedule board tree flow map pin

All data elements on one page →