Data

A chart stores its values in the document as Chart Data, a list of columns and a list of rows. However the values arrive, they end up there, so the chart draws offline, in an export and for every collaborator.

AlphaPilot program

A column has an id, a label and a role: 'label' for the column that names the rows, 'series' for a column of values. A row is a list of cells, one per column.

Where the data comes from

Way in	What happens	Page
Typed rows	Rows such as `Jan \| 2`, typed after `:::`, become a chart	Quick Input
A table	A table becomes a chart, or a chart follows a table while you edit the table	Tables
A file or a service	A chart keeps a snapshot of a CSV or JSON URL, or of a provider you write	Data Sources
Pasted text	A Mermaid chart becomes a chart, rows become a selected chart's new data	Pasting
Code	`insertChart` with Chart Data, or `insertChartFrom` with text in a format	Charts
An AI model	Tool calls that write through the same commands	Tools for a model

Which columns are drawn

The Chart Data keeps every column. The encoding field of the Chart Spec, the chart's settings, holds the ids of the columns the chart draws, in the editor and in every export:

Field	Description
`label`	The column that names the rows
`series`	The columns drawn, in that order
`seriesIn`	`'rows'` swaps rows and columns, see `setChartSeriesIn`

Without label, the column with the role 'label' names the rows.
Without series, every other column with the role 'series' is drawn.
An id that is not in the data is ignored, so a chart still draws after a source renames a column.
When no id in series is in the data, every series is drawn.
A synchronization replaces all columns and keeps encoding, see Data Sources.

Set encoding with updateChartSpec, or with the commands below.

Commands

updateChartData

Replaces the Chart Data.

editor.commands.updateChartData({ data })

Option	Type	Description
`data`	`ChartData`	The new Chart Data
`pos`	`number`	The chart's position. Defaults to the selected chart

Returns false when there is no chart at pos or selected, or when the chart's linked source is read-only and the new data differs from the current data.

setChartLabelColumn

Makes one column name the rows. encoding.series becomes every other column the chart type can draw.

editor.commands.setChartLabelColumn({ label: 'region' })

Option	Type	Description
`label`	`string`	The id of the column that names the rows
`pos`	`number`	The chart's position. Defaults to the selected chart

For most types, the drawn columns are those with the role 'series'. For a type that reads its rows with the matrix shape, such as the matrix chart type, it is every column, see Register your own chart type. Choosing the first column removes label and series from encoding. encoding.seriesIn is always kept.

Returns false for a column the data does not have.

setChartSeriesIn

Decides whether each column or each row of the data is a series. A series is one set of values the chart draws, such as one line or one color of bars.

editor.commands.setChartSeriesIn({ seriesIn: 'rows' })

Option	Type	Description
`seriesIn`	`'columns' \| 'rows'`	`'columns'` is the default. `'rows'` swaps the two
`pos`	`number`	The chart's position. Defaults to the selected chart

With 'rows', each row becomes a series named by its label, and each drawn column becomes a category. Take a bar chart of this data:

Month | Visitors
Jan   | 120
Feb   | 150
Mar   | 170

`seriesIn`	Categories	Bars in each category
`'columns'`	Jan, Feb, Mar	One bar, Visitors
`'rows'`	Visitors	Three bars, Jan, Feb, Mar

Only spec.encoding.seriesIn changes. label and series are kept. After the swap, spec.series styles are keyed by the row labels, and spec.palette colors the series in the order they are drawn.

updateChartFrom

Replaces the data and the spec from content in a registered format. Read a chart as Chart syntax, Chart JSON or Mermaid, change the text and write it back:

New tab

editor.commands.updateChartFrom({ format: 'chart-syntax', content: 'Jan | 2\nFeb | 3' })

Option	Type	Description
`format`	`string`	The id of a registered format
`content`	`string`	The content in that format
`pos`	`number`	The chart's position. Defaults to the selected chart

Returns false when the content cannot be read or the chart is read-only.

updateChartFromGrid

Replaces the data from a grid of strings.

editor.commands.updateChartFromGrid({ grid })

Option	Type	Description
`grid`	`string[][]`	Row 0 is the header, column 0 the labels
`pos`	`number`	The chart's position. Defaults to the selected chart

Use it with readGrid to edit the data in a form of input fields. Spreadsheet rows pasted onto a selected chart go through it.

Returns false in the same cases as updateChartData.

updateChartFromTable

Replaces the data from table JSON.

editor.commands.updateChartFromTable({ table })

Option	Type	Description
`table`	`JSONNode`	A table node as JSON
`pos`	`number`	The chart's position. Defaults to the selected chart

Use it with readTable, which returns a chart's data as table JSON.

Returns false in the same cases as updateChartData.

Helpers for tooling

From @tiptap-pro/extension-diagrams/core:

Function	Returns
`encodeChartData(data, encoding)`	The Chart Data a Renderer draws
`encodingForLabel(data, label, shape)`	The encoding `setChartLabelColumn` writes, without writing

PreviouslyA diagram from a table

Next upQuick Input