Excel charts

Design a chart in Excel once, then let each render fill it with that report’s numbers. The chart keeps the type, colors, fonts and layout you gave it; only the title and the series data change.

Type this as the chart’s title in Excel:

Sales {{year}}{{xlsxChart data=salesChart options=salesAxes}}

Render the template with this data:

{
  "year": 2026,
  "salesChart": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      { "label": "Online", "data": [120, 150, 170] },
      { "label": "Store", "data": [90, 85, 110] }
    ]
  },
  "salesAxes": {
    "scales": { "yAxes": [{ "ticks": { "min": 0, "max": 200, "stepSize": 50 } }] }
  }
}

The chart’s title becomes Sales 2026, it shows two series, Online and Store, over January to March, and its value axis runs from 0 to 200 in steps of 50.

Charts work in workbook templates, which render XLSX only.

Set up the chart

1. In Excel, put a few sample values in some cells, for example on a second sheet, and insert one of the supported chart types from them. Style it as you want the output to look.
2. Click the chart title and type the text you want, with {{xlsxChart data=...}} anywhere in it. The tag itself prints nothing, so a title that is only the tag renders empty.
3. Save the .xlsx and upload it as a workbook template, as in Spreadsheet templates.

How it fills the chart:

• The chart must have at least one series. Dataset 1 fills series 1, dataset 2 fills series 2, and so on, and each keeps that series’ formatting.
• Series without a dataset are removed. Datasets beyond the chart’s series are added after the last one, without its colors or marker symbol, so Excel picks their colors.
• The values are written into the chart itself, so the chart no longer reads the sample cells. The cells stay in the workbook as you left them.
• Other Handlebars in the title, such as {{year}}, renders with the template’s data. A title with Handlebars but no xlsxChart keeps the chart’s own data.
• Only the chart title is read; axis titles and other text are left as they are.

data and options are values from your data or from a helper call, such as data=(salesChartData rows) with a helper of your own in helpers.js; see Handlebars templates.

Chart data

data is an object with two arrays, and neither may be empty:

Field	Holds
labels	The categories, or the X values for scatter and bubble charts.
datasets	One object per series.
datasets[].label	The series name shown in the legend.
datasets[].data	The values, one per label.
datasets[].dataLabels	Scatter charts only: a label per point. See point labels.
datasets[].dataErrors	Error bar amounts per point. See error bars.

Chart types

Excel chart	labels	datasets[].data
Column and bar (2-D: clustered, stacked, 100%)	Category names	Numbers
Line, line with markers (2-D)	Category names	Numbers
Stock	Dates as YYYY-MM-DD	Numbers, one dataset per price series
Scatter (X Y)	X values	Y values
Bubble	X values	[y, size] pairs
Waterfall, funnel	Category names	Numbers (first dataset only)
Treemap, sunburst	Names, or a list of levels (below)	Sizes (first dataset only)
Histogram	Required, but not used	The values to group into bins

• A combo chart, such as columns with a line, works when every part is a supported type. Datasets fill the series in the order Excel stores them.

• For a treemap or sunburst with several levels, give labels as one array per level, top level first, each as long as data:

  {
    "labels": [
      ["Europe", "Europe", "Asia"],
      ["Germany", "France", "Japan"]
    ],
    "datasets": [{ "label": "Revenue", "data": [40, 25, 35] }]
  }

• Pie, doughnut, area, radar, surface, box and whisker, and 3-D charts are not supported. Their titles still render, but xlsxChart in them makes the render fail with an error such as Chart "pieChart" type is not supported.

Axes

options sets the axes of column, bar, line, stock, scatter and bubble charts. It is ignored for waterfall, funnel, treemap, sunburst and histogram charts.

{
  "scales": {
    "xAxes": [{ "display": false }],
    "yAxes": [{ "display": true, "ticks": { "min": 0, "max": 200, "stepSize": 50 } }]
  }
}

Field	Effect
xAxes	One entry per category axis, in the chart’s order.
yAxes	One entry per value axis, in the chart’s order.
display	false hides the axis; any other value shows it.
ticks.min, ticks.max	Value axes only: the lowest and highest value on the axis.
ticks.stepSize	Value axes only: the distance between major gridlines.

Scatter and bubble charts have two value axes, so both are set through yAxes. An axis without an entry keeps its Excel settings.

Point labels and error bars

In a scatter chart, dataLabels puts a label on each point. Each item is a string, or an object with value and position (left, right, center, top or bottom). Without a position, a label keeps the position set in Excel, or goes to the right.

{
  "labels": [1.2, 2.5, 3.1],
  "datasets": [
    {
      "label": "Plants",
      "data": [10, 14, 9],
      "dataLabels": ["Berlin", { "value": "Lyon", "position": "top" }, "Osaka"]
    }
  ]
}

In column, bar, line, stock, scatter and bubble charts, dataErrors sets error bars: one [plus, minus] pair per point, where a missing value counts as 0. Add error bars to the series in Excel first so they keep your style.

{
  "label": "Online",
  "data": [120, 150, 170],
  "dataErrors": [
    [10, 5],
    [12, 12],
    [8, 4]
  ]
}

When the render fails

The render fails when:

• data is missing, or labels or datasets is not a non-empty array.
• options is not an object.
• The chart has no series.
• The chart type is not supported.
• A stock chart label is not a YYYY-MM-DD date, or a bubble chart value is not a [y, size] pair.
• dataLabels or dataErrors is not an array.

Charts in PDF documents

xlsxChart fills charts in Excel files only. HTML templates do not run JavaScript, so a chart in a PDF must be an image; see What’s not supported.