Charts

A chart is a chart node, one block of the document like a paragraph or an image. It stores its values, the Chart Data, and its settings, the Chart Spec, so users can change both and undo it.
New tab

Quick start

insertChart() inserts a chart from values in your code. In an editor with Diagrams and a Renderer, set up as in A first chart, this inserts a bar chart and selects it:

editor.commands.insertChart({
  type: 'bar',
  data: {
    columns: [
      { id: 'month', label: 'Month', role: 'label' },
      { id: 'revenue', label: 'Revenue', role: 'series' },
    ],
    rows: [
      ['Jan', 120],
      ['Feb', 150],
    ],
  },
})

Chart types

The label column, with role: 'label', names the rows, such as Jan, and is the x axis. Each role: 'series' column is a series. The last column says what a chart becomes in Word:

TypeReads the rows asIn Word
line, areaA label column and seriesWord chart
scatterThe sameWord chart, an image when labels are numbers
barThe same, on their side with spec.orientation: 'horizontal'Word chart
comboThe same, see Combo chartsWord chart
radarA spoke per row, a closed line per seriesWord chart
pie, doughnutA label column and one seriesWord chart
funnelA label per stage and one value, drawn widest firstImage
gaugeThe first series' first value, on spec.range, 0 to 100 by defaultImage
treemap, treePaths as labels and the first series as values, see Trees and linksImage
sankey, networkA link per row, see Trees and linksImage
matrixWords in a grid, see MatrixWord table

A chart with reference lines becomes an image in Word too. A type the chart's Renderer cannot draw goes to the next registered one that can, see Choosing the Renderer.

The chartTypes option adds types, each with a ChartShape that says how it reads rows, such as cartesian for a label column and series. They are stored, listed in the tools for a model and drawn by any Renderer that lists them. An unknown type stays in the document and reads its rows as cartesian.

A treemap or tree row has a path as its label: Europe / Germany puts Germany under Europe. The slash needs a space on each side, so km/h stays one name. A parent needs no row, and then its value is the sum of its children.

A sankey or network row is a link. The label column is its start, and the next column, a series column of text, its end. The third is its weight, 1 when missing:

editor.commands.insertChartFrom({
  format: 'chart-syntax',
  type: 'sankey',
  content: 'From | To | Visits\nHome | Pricing | 120\nPricing | Signup | 40',
})

A row without a start or an end is skipped, and so is a link from a node to itself. On a sankey, a link that would close a loop is dropped too.

Combo charts

A combo chart draws some series as bars and others as lines, set in spec.series by column id. updateChartSpec replaces series as a whole, with its line styles. Both fields work only on a combo chart:

FieldValues
spec.series[columnId].as'bar' (default) or 'line'
spec.series[columnId].axis'left' (default) or 'right', a second value axis

Matrix

A matrix is a grid of words, such as a RACI matrix of who is responsible, accountable, consulted or informed. The label column holds the tasks, each other column a role:

Task   | Lead | Team | Board
Plan   | A    | R    | I
Build  | C    | R    |

The role columns are series columns that hold text. Each distinct text gets a series color: R, A, C and I first, in upper or lower case, then others in order. Empty cells stay empty. Of the built-in Renderers, only ECharts draws a matrix, and Mermaid source cannot hold one.

How a chart is stored

A chart's attributes hold everything needed to draw it again, each null until set:

AttributeContent
dataChart Data: columns (id, label, role of 'label' or 'series') and rows
specChart Spec, see Chart Spec fields, with the chart's size in spec.size
rendererThe id of the chosen Renderer, null for the default
sourceThe Data Source the data was read from, such as a CSV file
syncedAtWhen the data was last read from its source, as an ISO time
delimiterThe delimiter the data was typed with, kept for editing it as text again
previewUrlAn image URL for the HTML output and the export copy. No command sets it yet

In HTML

A chart is a <figure data-type="chart">. Its data is a <table>, so the numbers survive an HTML or Markdown export and a screen reader reads them. The <figcaption> holds the title, or title: description with spec.caption: true. The rest is in data attributes, the spec and source as JSON.

More about charts

See Appearance, Axes, Reference lines and bands, Looks and Editing in the chart.

Commands

insertChart

Inserts a chart at the selection, or at pos, and selects it. Without data, it starts empty:

editor.commands.insertChart({ type: 'line', pos: 0 })
OptionTypeDefaultDescription
dataChartDataEmptyThe Chart Data
specPartial<ChartSpec>NoneThe Chart Spec. Wins over look
typeChartTypechart.defaultType, 'line'Shortcut for spec.type. Wins over the look's type
rendererstring | nullnull, the defaultThe Renderer id
sourceChartSource | nullnullThe Data Source the chart follows
delimiterstring | nullnullThe delimiter the data was typed with
posnumberThe selectionWhere to insert
lookChartLookNoneA look to start with, see applyChartLook

An empty paragraph at the selection is replaced. With a chart selected, the new one goes after it.

Returns false when the schema has no chart node, or when a block cannot go at that position.

insertChartFrom

Inserts a chart written in a registered format. The chart keeps the delimiter the content used.

editor.commands.insertChartFrom({
  format: 'chart-syntax',
  content: 'Month | Revenue\nJan | 120\nFeb | 150',
})
OptionTypeDefaultDescription
formatstringRequired'chart-json' ({ spec, data } as JSON), 'chart-syntax', 'mermaid', or one from the formats option
contentstringRequiredThe text in that format
typeChartTypechart.defaultTypeUsed when the content names no type
rendererstring | nullnullThe Renderer id
posnumberThe selectionWhere to insert

Returns false when no format has that id, when the content cannot be read, or when insertChart would return false.

importMermaidChart

Inserts a chart from Mermaid chart source. Mermaid is a library that draws diagrams and charts from text.

editor.commands.importMermaidChart({ source: 'pie\n  "Dogs" : 386\n  "Cats" : 85' })
OptionTypeDefaultDescription
sourcestringRequiredThe Mermaid source
posnumberThe selectionWhere to insert

These Mermaid kinds become charts:

First lineChart typeData
piepieA row per slice
xychart-beta or xychartbar or lineA row per category, a series per bar or line. line only without bars. Keeps the y range and x title
sankey-beta or sankeysankeyA row per flow: source, target, value
radar-betaradarA row per axis, a series per curve. Keeps min and max
treemap-beta or treemaptreemapA row per node with a value, labeled by its path, A / B

The title comes from title, or else the frontmatter, and accDescr becomes the description. Mermaid's styling (classDef, showLegend, ticks, graticule) is left out. Pasting such source runs this command, see Pasting.

toMermaidSource from @tiptap-pro/extension-diagrams/core and the mermaid format write the five kinds back. Pie, radar and treemap take no negative numbers in Mermaid. So a pie slice of zero or less, an empty cell and a negative treemap node are left out, and a negative radar value becomes zero. An xychart keeps negative values.

Returns false for any other Mermaid diagram, and for chart source it cannot read, such as a pie line that is not "Label" : 42.

convertCodeBlockToChart

Replaces a code block with the chart its Mermaid chart source describes. Any node with code: true counts as one, except the Quick Input's diagramInput node.

if (editor.can().convertCodeBlockToChart()) editor.commands.convertCodeBlockToChart()
OptionTypeDefaultDescription
posnumberThe selectionA position inside the code block

Mod-Enter in the code block runs the command too, see Mod-Enter in a code block.

Returns false when there is no code block at the position, when it holds anything else than Mermaid chart source, or when that source has no rows.

insertDiagramInput

Opens an empty Quick Input, a text field in the document whose rows become a chart, at the selection with the cursor in it. Typing the trigger ::: does the same.

editor.chain().focus().insertDiagramInput({ type: 'pie' }).run()
OptionTypeDefaultDescription
typeChartTypechart.defaultTypeThe type the Quick Input starts with

The Quick Input is the diagramInput node. Diagrams adds it with the chart node, unless its chart option is false. Keys in the Quick Input says how users confirm.

Returns false when the schema has no diagramInput node, or when a block cannot go at the selection.