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 of a shared document.

Where the data comes from

Way inWhat happensPage
Typed rowsRows such as Jan | 2, typed after :::Quick Input
A tableA table becomes a chart, or a chart updates with itTables
A URLA copy of a CSV or JSON file, or of a serviceData Sources
Pasted textMermaid charts, or rows onto a selected chartPasting
CodeinsertChart or insertChartFromCharts
An AI modelTool callsTools for a model

Quick start

In the editor from A first chart, this call inserts a bar chart from Chart Data:

editor.commands.insertChart({
  type: 'bar',
  data: {
    columns: [
      { id: 'month', label: 'Month', role: 'label' },
      { id: 'retail', label: 'Retail', role: 'series' },
    ],
    rows: [
      ['Jan', 30],
      ['Feb', null],
    ],
  },
})

Chart Data

A column has an id, a label, which is the header in the legend and on the axis, and a role: 'label' names the rows, 'series' holds values.

Typed rows and tables get ids from the labels, in lowercase with dashes, so Net revenue becomes net-revenue, and a second Net revenue becomes net-revenue-2.

A row holds one cell per column: a string, a number or null. null is a gap, drawn as a missing value, not as zero, so February in the quick start gets no bar.

Which columns are drawn

The Chart Data keeps every column. Which ones a chart draws is set in encoding, by column id. encoding is part of the Chart Spec, the chart's settings, which insertChart takes as spec:

FieldDefaultDescription
labelThe column with role 'label', else the firstThe column that names the rows
seriesEach column with role 'series' but labelThe columns drawn, in order. A series is one line or one bar color
seriesIn'columns''rows' swaps rows and columns, see setChartSeriesIn

An id that is not in the data is ignored. When no series id is in the data, every series is drawn. Set encoding with updateChartSpec or the commands on this page.

Commands

Each command acts on the chart at pos, a position in the document, or else on the selected chart. It returns false when there is no such chart.

updateChartData

Replaces the Chart Data and keeps the Chart Spec.

editor.commands.updateChartData({ data })
OptionTypeDefaultDescription
dataChartDataRequiredThe new Chart Data
posnumberThe selected chartThe chart's position

Returns false when the chart is linked to a read-only Data Source and the data differs from its current data. Invalid data throws a ChartDataError from @tiptap-pro/extension-diagrams/core.

setChartLabelColumn

Makes another column name the rows, such as the categories along the x-axis. label takes the column's id, which for this data is region:

Month | Region | Revenue
Jan   | North  | 10
editor.commands.setChartLabelColumn({ label: 'region' })
OptionTypeDefaultDescription
labelstringRequiredThe id of the column that names the rows
posnumberThe selected chartThe chart's position

The chart then names its bars by region and draws Revenue. Month, with the role 'label', is not drawn. For the matrix chart type, whose cells hold words, every other column is drawn. Choosing the first column goes back to the default. encoding.seriesIn is kept.

Returns false for a column id the data does not have.

setChartSeriesIn

Decides whether each column or each row of the data is a series.

editor.commands.setChartSeriesIn({ seriesIn: 'rows' })
OptionTypeDefaultDescription
seriesIn'columns' | 'rows'RequiredWhat a series is
posnumberThe selected chartThe chart's position

With 'rows', each row becomes a series named by its label, and each drawn column a category. So a bar chart of Month | Visitors with the rows Jan, Feb and Mar shows one Visitors category with three bars instead of three months with one bar each.

After the swap, a style set for one series applies by row id, such as jan.

Returns false only without a chart.

updateChartFrom

Replaces the data and the Chart Spec from text in a format: chart-syntax (the Chart syntax), chart-json, a JSON object { spec, data }, or mermaid. The formats option adds your own. In the demo, read a chart in each format, change the text and write it back:

New tab
editor.commands.updateChartFrom({ format: 'chart-syntax', content: 'Jan | 2\nFeb | 3' })
OptionTypeDefaultDescription
formatstringRequiredThe id of a registered format
contentstringRequiredThe text in that format
posnumberThe selected chartThe chart's position

The Chart syntax carries only a type, so the title and colors go back to their defaults. Text without a type line keeps the chart's type.

Returns false without a chart, when the text cannot be read, or when the chart is linked to a read-only Data Source and the data would change. It does not throw.

updateChartFromGrid

Replaces the data from a grid of strings, such as the values of a form you build for editing the data. readGrid returns a chart's current grid.

editor.commands.updateChartFromGrid({
  grid: [
    ['Month', 'Sales'],
    ['Jan', '2'],
  ],
})
OptionTypeDefaultDescription
gridstring[][]RequiredRow 0 is the header, column 0 the labels
posnumberThe selected chartThe chart's position

Empty rows at the end are dropped, and numbers are read with the chart.decimalSeparator option. Returns false in the cases of updateChartData.

updateChartFromTable

Replaces the data from a table node as JSON, such as a table's toJSON() or what readTable returns.

editor.commands.updateChartFromTable({ table })
OptionTypeDefaultDescription
tableJSONNodeRequiredA table node as JSON
posnumberThe selected chartThe chart's position

Returns false in the cases of updateChartData.

Helpers for tooling

Code without an editor, such as your own Renderer or a test, can work out which columns a chart draws with encodeChartData and encodingForLabel from @tiptap-pro/extension-diagrams/core. Here, parseChartSyntax turns text into Chart Data:

import {
  chartShape,
  encodeChartData,
  encodingForLabel,
  parseChartSyntax,
} from '@tiptap-pro/extension-diagrams/core'

const { data } = parseChartSyntax('Month | Region | Revenue\nJan | North | 10')

encodeChartData(data, { series: ['revenue'] }) // Chart Data with the columns Month and Revenue
encodingForLabel(data, 'region', chartShape('bar')) // { label: 'region', series: ['revenue'] }
  • encodeChartData(data, encoding) returns the Chart Data a chart with this encoding draws. @tiptap-pro/extension-diagrams exports it too.
  • encodingForLabel(data, label, shape) returns the encoding that setChartLabelColumn would write: undefined for the first column, which needs none, and null for a missing column. shape is how the chart type reads its data, such as 'cartesian' for a bar chart or 'matrix' for a grid of words, and chartShape(type) returns it.