D3 Renderer

The D3 Renderer draws charts as SVG with D3, a data drawing library. A customizer changes a drawn chart in code.

Quick start

Install D3 (^7.9.0) and register the Renderer:

npm install d3
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { d3Renderer } from '@tiptap-pro/extension-diagrams/d3'

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

Install Diagrams has the complete editor around these lines.

Chart types

The D3 Renderer draws line, bar, area, scatter, pie, doughnut, radar, combo, tree and network charts, and sankey charts. It does not draw matrix, funnel, gauge or treemap.

  • Network is laid out the same way every time for the same data.
  • orientation: 'horizontal' lays bars on their side, except in a combo chart.

It draws every field of series line styles, axes and reference lines, and renames a text on a double click (Editing in the chart).

Options

OptionTypeDefaultDescription
idstring'd3'The id charts store
labelstring'd3'The name for a menu
customizersRecord<string, D3Customizer>NoneCustomizers by name
measureText(text, fontSize) => numberNoneA label's width in pixels, for exact layout. Without it, estimated from the number of characters
createDocument() => DocumentNoneThe Document for toSVG without a global one
sankeythe d3-sankey moduleNoneDraws sankey charts

Sankey charts

Install d3-sankey (^0.12.3) and pass it as sankey. Without it, the D3 Renderer does not draw sankey charts: another registered Renderer that draws them does, and with none a sankey chart shows no picture.

import * as sankey from 'd3-sankey'

d3Renderer({ sankey })

Customizers

A customizer is a function you register under a name, which a chart refers to:

d3Renderer({
  customizers: {
    highlightMax(svg, { data }) {
      // change the drawn SVG element: add marks, reorder, restyle
    },
  },
})

editor.commands.updateChartSpec({ spec: { renderer: { d3: { customizer: 'highlightMax' } } } })

It gets the drawn SVGSVGElement and the render input after every draw, in the editor and in exports, and returns nothing. The document stores only the name, so a chart naming a customizer this editor lacks is drawn without one.

Export and servers

On a server, call toSVG as the ECharts Renderer shows, and pass createDocument, such as from the DOM library linkedom:

import { parseHTML } from 'linkedom'

d3Renderer({
  createDocument: () => parseHTML('<!doctype html><html><body></body></html>').document,
})

Without it, toSVG throws "The d3 Renderer needs createDocument to export without a browser."