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.Pilot programAlpha
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 []:
| Field | Type | Description |
|---|---|---|
id | string | Stored in spec.type: up to 64 letters, digits, _ and -. Other ids are left out |
label | string | For 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 |
description | string | Optional. One sentence for an AI model |
The data layouts of shape:
shape | Columns and rows | Built-in types, for example |
|---|---|---|
cartesian | A label column and one or more series | line, bar, radar, combo |
radial | A label column and one series, the parts of a whole | pie, funnel |
single | One value | gauge |
hierarchy | Labels as paths, such as A / B, and a value per leaf | treemap, tree |
matrix | Words in a grid, such as who does what | matrix |
graph | A source column, a target column and a value per link | sankey, 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:
- after
:::in the Quick Input, the text field for chart rows, - by the command
setDiagramInputType, - to AI models, through the tools and
editor.storage.diagrams.describeCapabilities(), with itsid,label,shapeanddescription. An entry with a built-in id replaces that type's definition, such as its label.
Reading rows like the built-in types
These functions from @tiptap-pro/extension-diagrams read input.data like the built-in types:
| Function | Reads rows like | Returns |
|---|---|---|
chartHierarchy(data) | hierarchy | A 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 |