Register your own chart type

A chart type is the id a chart stores in spec.type, such as bar. To add a type of your own, register it with the chartTypes option, and list it in the types of the Renderer that draws it.

Quick start

This adds a chord chart, drawn by a Renderer of your own. chordSvg(input) stands for your code that draws chartLinks(input.data) as standalone SVG markup:

import { Diagrams, type ChartRenderer, type ChartRenderInput } from '@tiptap-pro/extension-diagrams'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'

const chordRenderer: ChartRenderer = {
  id: 'chord',
  label: 'Chord',
  types: ['chord'],
  mount(target, input) {
    const draw = (next: ChartRenderInput) => {
      const svg = new DOMParser().parseFromString(chordSvg(next), 'image/svg+xml').documentElement
      target.replaceChildren(target.ownerDocument.importNode(svg, true))
    }
    draw(input)
    return { update: draw, destroy: () => target.replaceChildren() }
  },
  async toSVG(input) {
    return chordSvg(input)
  },
}

Diagrams.configure({
  renderers: [echartsRenderer(), chordRenderer],
  chartTypes: [
    {
      id: 'chord',
      label: 'Chord',
      shape: 'graph',
      word: 'image',
      description: 'Flows between groups drawn around a circle: from, to and how much.',
    },
  ],
})

Members has the rest of a Renderer.

Fields of a chart type

chartTypes takes an array of these objects, and defaults to []:

FieldTypeDescription
idstringStored in spec.type: up to 64 letters, digits, _ and -. Other ids are left out
labelstringFor a menu
shape'cartesian' | 'radial' | 'single' | 'hierarchy' | 'matrix' | 'graph'The data layout, also of the example rows in the Quick Input
word'chart' | 'table' | 'image'Required. Its form in Word. Use 'image', see Word charts and tables
descriptionstringOptional. One sentence for an AI model

The data layouts of shape:

shapeColumns and rowsBuilt-in types, for example
cartesianA label column and one or more seriesline, bar, radar, combo
radialA label column and one series, the parts of a wholepie, funnel
singleOne valuegauge
hierarchyLabels as paths, such as A / B, and a value per leaftreemap, tree
matrixWords in a grid, such as who does whatmatrix
graphA source column, a target column and a value per linksankey, network

A document keeps a type that no editor registered, and reads it as cartesian.

Word charts and tables

Word charts and tables exist only for built-in types. A type of your own becomes an image in Word, even with word: 'chart' or 'table', see Export.

Where a registered type appears

A registered type is offered like a built-in one:

Reading rows like the built-in types

These functions from @tiptap-pro/extension-diagrams read input.data like the built-in types:

FunctionReads rows likeReturns
chartHierarchy(data)hierarchyA tree of { name, path, value, total, children } from paths like Europe / Germany
chartLinks(data)graph{ nodes, links }, a link per row with two different ends, value 1 by default