Data
Where the data comes from
| Way in | What happens | Page |
|---|---|---|
| Typed rows | Rows such as Jan | 2, typed after ::: | Quick Input |
| A table | A table becomes a chart, or a chart updates with it | Tables |
| A URL | A copy of a CSV or JSON file, or of a service | Data Sources |
| Pasted text | Mermaid charts, or rows onto a selected chart | Pasting |
| Code | insertChart or insertChartFrom | Charts |
| An AI model | Tool calls | Tools 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:
| Field | Default | Description |
|---|---|---|
label | The column with role 'label', else the first | The column that names the rows |
series | Each column with role 'series' but label | The 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 })| Option | Type | Default | Description |
|---|---|---|---|
data | ChartData | Required | The new Chart Data |
pos | number | The selected chart | The 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 | 10editor.commands.setChartLabelColumn({ label: 'region' })| Option | Type | Default | Description |
|---|---|---|---|
label | string | Required | The id of the column that names the rows |
pos | number | The selected chart | The 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' })| Option | Type | Default | Description |
|---|---|---|---|
seriesIn | 'columns' | 'rows' | Required | What a series is |
pos | number | The selected chart | The 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:
editor.commands.updateChartFrom({ format: 'chart-syntax', content: 'Jan | 2\nFeb | 3' })| Option | Type | Default | Description |
|---|---|---|---|
format | string | Required | The id of a registered format |
content | string | Required | The text in that format |
pos | number | The selected chart | The 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'],
],
})| Option | Type | Default | Description |
|---|---|---|---|
grid | string[][] | Required | Row 0 is the header, column 0 the labels |
pos | number | The selected chart | The 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 })| Option | Type | Default | Description |
|---|---|---|---|
table | JSONNode | Required | A table node as JSON |
pos | number | The selected chart | The 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 thisencodingdraws.@tiptap-pro/extension-diagramsexports it too.encodingForLabel(data, label, shape)returns theencodingthatsetChartLabelColumnwould write:undefinedfor the first column, which needs none, andnullfor a missing column.shapeis how the chart type reads its data, such as'cartesian'for a bar chart or'matrix'for a grid of words, andchartShape(type)returns it.