ECharts Renderer

The ECharts Renderer draws charts as SVG with ECharts, a chart library. It draws every built-in chart type.

Quick start

Install ECharts (^6.0.0) and register the Renderer:

npm install echarts
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'

Diagrams.configure({ renderers: [echartsRenderer()] })

Install Diagrams has the complete editor around these lines.

Chart types

The ECharts Renderer draws line, bar, area, scatter, pie, doughnut, matrix, radar, funnel, gauge, treemap, combo, tree, sankey and network charts. It supports orientation: 'horizontal' in bar and combo charts, and every option of series line styles, axes and reference lines.

  • Matrix is a heatmap of colored cells with their text inside. Its legend lists each value.
  • Network is laid out on a circle, so it looks the same every time.

A double click on a text renames it, see Editing in the chart. Charts animate in the editor unless animation is off or the user's system asks for reduced motion.

Options

OptionTypeDefaultDescription
idstring'echarts'The id charts store
labelstring'ECharts'The name for a menu

Options a chart can store

A chart can store ECharts options under spec.renderer.echarts. The Renderer merges them into the ECharts option it builds, key by key at the top level:

editor.commands.updateChartSpec({
  spec: { renderer: { echarts: { grid: { left: 80 }, legend: { icon: 'circle' } } } },
})

An object merges with the option of the same name, and any other value replaces it. The Renderer leaves out these values and keeps the rest:

  • a tooltip's formatter and extraCssText,
  • a color that is not a CSS color (CSS colors are such as #1d3557, rgb(…) or var(…)),
  • a text value with a double quote, and a font family with ;, <, >, \ or brackets,
  • a link or sublink that is not an http: or https: address.

Export and servers

In the editor, export a chart with editor.storage.diagrams.export. On a server, call the Renderer's toSVG yourself. It needs no DOM, so it runs in Node.js. chart stands for a chart node of the stored JSON, { type: 'chart', attrs: { data, spec } }:

import { defaultChartTheme, encodeChartData } from '@tiptap-pro/extension-diagrams'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'

const { data, spec } = chart.attrs
const svg = await echartsRenderer().toSVG({
  data: encodeChartData(data, spec.encoding),
  spec,
  theme: defaultChartTheme,
  size: { width: 800, height: 450 },
})

encodeChartData picks the columns the chart shows. defaultChartTheme holds the default colors and fonts. To draw with an ECharts setup of your own, toEChartsOption(data, spec, theme) from the same entry point returns the ECharts option, without spec.renderer.echarts.