Charts

Quick start

editor.commands.insertFromText({ text: 'Month | Sales\nJan | 2\nFeb | 3' })

insertFromText reads the text the way a paste would, so these rows become a chart. The rows are written in the Chart syntax.

More about charts

Chart types

A chart stores its type as spec.type. Most types read the Chart Data the same way. One column is the label column, usually the first: its cells name the rows, such as Jan and Feb. Each other column of numbers is a series, drawn as one line, one set of bars or one set of points.

The last column says what a chart becomes in a Word document: a native Word chart that you can restyle in Word, an image, or a Word table.

• Not every Renderer draws every type. A Renderer that does not draw a type leaves the chart to the next one that does, see Choosing the Renderer.
• A sankey link that would close a loop is dropped.
• A type you register with the chartTypes option is stored, offered to an AI model and drawn by any Renderer that lists it.
• A type this editor does not know stays in the document unchanged.

Combo charts

A combo chart draws some series as bars and others as lines. You choose this per series, by column id:

Matrix

A matrix is a grid of words, such as a RACI matrix. The label column holds the tasks, each other column is a role, and each cell holds a letter.

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

Each distinct cell text gets a color from the series colors. R, A, C and I come first, in that order. The ECharts Renderer draws a matrix. A matrix cannot be written as Mermaid.

How a chart is stored

A chart's attributes hold everything needed to draw it again:

The document never stores the drawn chart, the size it was drawn at on screen, or its loading state. A size you set is stored in spec.size.

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 can read them. Its title is the <figcaption>. The Chart Spec and the Data Source are stored as JSON in data-tt-chart-* attributes on the <figure>, see Data attributes.

Commands

insertChart

Inserts a chart at the selection, or at pos, 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],
    ],
  },
})

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

insertChartFrom

Inserts a chart written in a registered format.

editor.commands.insertChartFrom({
  format: 'chart-syntax',
  content: 'Month | Revenue\nJan | 120\nFeb | 150',
})

Returns false when the content cannot be read.

importMermaidChart

Inserts a chart from Mermaid chart source.

editor.commands.importMermaidChart({ source: 'pie\n  "Dogs" : 386\n  "Cats" : 85' })

Mermaid draws most of its kinds as diagrams. These five kinds hold numbers, so they become charts with data you can edit:

• The chart's title comes from title, or from frontmatter for sankey and treemap.
• How Mermaid colors the chart (classDef, showLegend, ticks, graticule) is left out.
• toMermaidSource and the mermaid format turn a chart back into Mermaid source. They write the same five kinds.
• Mermaid's pie, radar and treemap read no minus sign, so they cannot show a value below zero. When such a chart is written back to Mermaid, a pie slice or a treemap node below zero is left out, and a radar value below zero is written as zero.

Pasting Mermaid chart source runs this command, see Pasting.

Returns false for any other Mermaid diagram.

convertCodeBlockToChart

Replaces a code block with the chart its Mermaid chart source describes.

if (editor.can().convertCodeBlockToChart()) editor.commands.convertCodeBlockToChart()

Any node with code: true in its spec counts as a code block. Mod-Enter in the code block runs the command too, see Mod-Enter in a code block.

Returns false for a code block holding anything else.

insertDiagramInput

Opens an empty Quick Input at the selection, as typing the trigger does.

editor.chain().focus().insertDiagramInput({ type: 'pie' }).run()

Returns false when the schema has no diagramInput node.