Export

Export a chart or a diagram as an SVG, PNG, WebP or JPEG file, or put charts and diagrams into a Word document. Exporting reads the document and changes nothing. Only the commands, which replace a chart with an image of it, change the document.
New tab

Quick start

In the editor of A first chart, which selects the chart it inserts, these lines save that chart as a PNG file. downloadBlob offers a Blob as a download:

import { downloadBlob } from '@tiptap-pro/extension-diagrams/export'

const { blob } = await editor.storage.diagrams.export(
  {},
  { format: 'png', scale: 2, background: '#ffffff' },
)
downloadBlob(blob, 'chart.png')

Files

editor.storage.diagrams.export(target, options) returns a promise of one file. The file has the border and caption the editor shows, and the credit link that a Renderer may require.

editor.storage.diagrams.exportAll(options) returns a promise of an array of the same results, each with its pos, for every drawable chart and diagram in document order.

What to export

The first argument, target, is one of:

TargetExports
{ pos? }The chart or diagram at pos, a position such as listCharts() returns, or the selected one with {}
{ data, spec, renderer? }Chart Data that is in no document

A diagram is drawn by its Diagram Renderer, such as the Mermaid one, and its colors come from the --tt-flow-diagram-* custom properties.

Options

OptionTypeDefaultDescription
format'svg' | 'png' | 'webp' | 'jpeg''svg'The file format
scalenumber2Image pixels per pixel of size. 2 gives 1600 px for 800
backgroundstring | nullnullA fill behind the chart in an image. A JPEG without one is white
rendererstringThe chart'sDraw with another Renderer, charts only
themeChartThemeThe page'sColors and fonts instead of the page's custom properties, charts only
size{ width: number; height: number }{ width: 800, height: 450 }, or 800 wide at the chart's own ratioThe size to draw at, charts only
scheme'light' | 'dark''light'The color scheme, whatever the page shows. Light on a server

What comes back

FieldContent
blobThe file
svgThe SVG, with concrete colors instead of var(…), so it looks the same anywhere
width, heightThe size of the drawing
altThe title and description, for an alt attribute. Else <type> chart or Diagram
rendererThe id of the Renderer it was drawn with
rastertrue when the Renderer drew pixels. The SVG then holds an image, which does not scale without loss

PNG, WebP and JPEG need a browser. ECharts and D3 SVGs can be made on a server. The mermaid.js, draw.io and BPMN Diagram Renderers draw only in a browser, so on a server only Pele's renderPeleDiagram draws a diagram. The promise rejects without a chart or diagram, without a Renderer for it, or for a format the Renderer's rules, the export formats it allows, forbid.

For an SVG of your own, /export also has svgToBlob(svg), svgToImage(svg, options), toDataUrl(blob), readSvgSize(svg), inlineSvgStyles and rasterToSvg.

Word

There are three ways to get charts into Word. A native Word chart is drawn by Word, the user can restyle it there, and "Edit data" opens its data in Excel.

WayWhat the Word file holds
editor.storage.diagrams.exportDocx()Only the charts and diagrams. Native Word charts where Word can draw them, and diagrams as images where they can be drawn
toPortableContent with ExportDocxThe whole document. Each chart is an image, a table or both, and each diagram is an image or its source
toPortableContent with charts: 'native', then addNativeChartsThe whole document, with native Word charts

Charts and diagrams only

exportDocx writes a Word file of only the charts and diagrams, a promise of { blob, notes }:

import { downloadBlob } from '@tiptap-pro/extension-diagrams/export'

const { blob, notes } = await editor.storage.diagrams.exportDocx({
  targets: [{ pos }],
  title: 'Report',
})
downloadBlob(blob, 'charts.docx')
for (const note of notes) console.info(note.title ?? 'All charts', note.message)

exportDocx takes these options:

OptionTypeDefaultDescription
targetsChartTarget[]See What the file holdsTargets to write, in order
titlestringNoneA heading above the charts
fallbackFontstring'Arial'The font Word uses when it lacks the page's font
images'auto' | 'always'docxImages optionSee Charts as images

What the file holds

Each target becomes a native Word chart with its data in an embedded workbook, a Word table, or a PNG image. Without targets, the file holds every chart with data, except one with the layout 'table', and every diagram with source.

Colors and the font come from the page, in light.

  • A native Word chart whose Chart Spec has caption: true has its description below, in Caption style.
  • A chart as an image has that description drawn in, and its title below.
  • A diagram is a PNG image with its title below, scaled down to the page width when wider.
  • A matrix chart is a Word table with shaded cells and its title above.

A chart or diagram with a size takes that share of the page width. Alt text holds the title and description. A diagram that cannot be drawn, such as on a server, is left out with a note. A chart that cannot be drawn becomes a native Word chart, or is left out when Word has no form for its type, see Charts as images. The promise rejects only when there is nothing to write, or nothing could be written.

Charts as images

images decides when a chart becomes a PNG image instead of a native Word chart:

imagesWhat a chart becomes
'always'A PNG image drawn by its Renderer, 800 wide at the chart's aspect ratio
'auto'A Word chart or table when Word has a form for the type, else an image. Also an image in the two cases below
Left outThe docxImages option decides, 'auto' by default

With 'auto', a scatter chart with numbers on its x axis becomes an image, because Word would space the x values evenly. So does a chart with reference lines, because Word charts have none.

No image can be drawn when no Renderer draws the chart or its rules forbid docx. Then a type with a Word form becomes a Word chart, and another type is left out, with a note.

Notes

notes lists what Word shows differently, as { pos, title, message }. pos and title are null for a note about the whole file. Notes cover:

  • a font Word lacks, listed first,
  • only the first series of a pie or doughnut chart with several,
  • the x axis range, which Word ignores,
  • a background, series or axis color that is not a hex value,
  • grid lines or labels at only some categories, which Word puts at every category,
  • a value grid line without the category axis line,
  • area edges with series styles, which Word draws in its own line style,
  • options only one Renderer understands,
  • a linked chart's snapshot of its data,
  • a matrix as a Word table,
  • a chart as an image, and why when its type has a Word form,
  • a chart left out, or a Word chart, because no image could be drawn,
  • a diagram as an image, or left out because it could not be drawn.

Without exporting

These functions from @tiptap-pro/extension-diagrams/core tell you what Word gets, without writing a file:

FunctionReturns
wordForm(type, images?)What a type becomes: 'chart', 'table' or 'image'
wordChartForm(data, spec, images?)What one chart becomes: 'chart', 'table' or 'image'
wordLimitations(data, spec, { theme, source?, images? })The messages of notes for one chart, as string[]

data, spec and source are a chart node's attributes of those names. For theme, pass defaultChartTheme from /core.

A whole document

A converter that does not know the chart and flowDiagram nodes leaves them out. So export the copy that toPortableContent from @tiptap-pro/extension-diagrams/core returns, in which charts and diagrams are tables, images and paragraphs. The document you pass in stays as it is, and no browser is needed.

This example sends the copy to Tiptap's Convert service with @tiptap-pro/extension-export-docx. CONVERT_TOKEN is your Convert API token, see the export-docx docs:

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { toPortableContent } from '@tiptap-pro/extension-diagrams/core'
import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const file = await new Promise((resolve, reject) => {
  const exporter = new Editor({
    element: null,
    content: toPortableContent(editor.getJSON()),
    extensions: [
      ConvertKit,
      ExportDocx.configure({ token: 'CONVERT_TOKEN', onCompleteExport: resolve, onError: reject }),
    ],
  })
  exporter.commands.exportDocx()
})

What the copy holds

In the documentIn the copy
A chartIts image, if it has one, and its data as a table
A chart with the layout 'table'Nothing, because only the table it follows shows
A diagramIts image from imageFor, else its title and its source as code-formatted lines
An open Quick Input, the field after :::Its text as code-formatted lines

With the default charts: 'both', a chart has its image and its table in the copy when it has a previewUrl or your imageFor returns one, and only its table otherwise. No command sets previewUrl yet. Without an image, the chart's title is a line above the table. A chart with caption: true has its description below.

A matrix cell keeps its colors as a background attribute and a textStyle mark, so a converter that reads them keeps the colors.

Options

OptionValueDefault
charts'both', 'image' (else the table), 'table' or 'native''both'
imageFor(figure) => url | null, figure is { kind: 'chart' | 'flowDiagram', attrs }A chart's previewUrl
sources'paragraphs', one code-formatted paragraph per line, or 'codeBlock' (language mermaid or xml)'paragraphs'
namesYour names for table, tableRow, tableHeader, tableCell, paragraph, image, codeBlockStarterKit's and @tiptap/extension-table's
decimalSeparator'.' or ',' for numbers in a table'.'
themeThe ChartTheme for a matrix chart's cell colorsdefaultChartTheme, from /core

Choose 'codeBlock' for a converter that writes code blocks, such as one to Markdown or HTML, and 'paragraphs' for one that leaves them out.

Native Word charts

A whole document with native Word charts takes two steps. First, toPortableContent with charts: 'native' writes a marker paragraph, such as {{tiptap-diagrams-chart-1}}, for each chart of a type Word draws itself: bar, line, area, scatter, pie, doughnut, radar and combo. Other types are written as with 'both'.

Any converter then writes the Word file. Second, addNativeCharts replaces each marker in that file with a native Word chart:

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { addNativeCharts, toPortableContent } from '@tiptap-pro/extension-diagrams/core'
import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const doc = editor.getJSON()
const exported = await new Promise((resolve, reject) => {
  const exporter = new Editor({
    element: null,
    content: toPortableContent(doc, { charts: 'native' }),
    extensions: [
      ConvertKit,
      ExportDocx.configure({
        token: 'CONVERT_TOKEN',
        exportType: 'buffer',
        onCompleteExport: resolve,
        onError: reject,
      }),
    ],
  })
  exporter.commands.exportDocx()
})
const docx = addNativeCharts({ docx: exported, doc })

addNativeCharts returns the Word file as a Uint8Array. Pass it the document you passed to toPortableContent, because it finds the charts by their order. A marker the converter split or changed stays as text. It also takes theme (default defaultChartTheme) and fallbackFont (default 'Arial').

'native' decides by the type alone. A scatter chart or a chart with reference lines becomes a native chart, where exportDocx with 'auto' may write an image.

Commands

These commands turn a chart into an image and back.

convertChartToImage

Replaces a chart with an image of it, a node of the type the imageNodeName option names, 'image' by default.

editor.commands.convertChartToImage({ format: 'svg', keepData: true })
OptionTypeDefaultDescription
format'svg' | 'png' | 'webp' | 'jpeg''png'The image format
keepDatabooleantrueThe image keeps the chart, so convertImageToChart brings it back
posnumberThe selected chartThe chart's position

The uploadImage option uploads the image, else it is a data URL. The chart is replaced once the image is ready, unless the chart changed meanwhile. A failed export or upload is only logged.

The image has twice the pixels it shows at, to stay sharp on high-density screens. An image node with a width attribute, such as @tiptap/extension-image, gets the export's width, 800 by default. Give images max-width: 100% so they shrink on a narrow screen:

.tiptap img {
  max-width: 100%;
  height: auto;
}

Returns false without a chart, without the image node in the schema, or when no Renderer draws the chart.

convertImageToChart

Turns an image made with keepData back into the chart, and selects the chart.

editor.commands.convertImageToChart()
OptionTypeDefaultDescription
posnumberThe selected imageThe image's position

Returns false for an image that keeps no chart.

redrawChartImage

Draws an image made with keepData again from the chart it keeps, with the current styles, Renderers and color scheme.

editor.commands.redrawChartImage({ pos })
OptionTypeDefaultDescription
format'svg' | 'png' | 'webp' | 'jpeg''png'The image format
posnumberThe selected imageThe image's position

Once the file is ready, only the image's src, alt, title and width change, in one undo step, unless the image changed meanwhile. It stays an image and keeps its chart.

Returns false for an image that keeps no chart, and when no Renderer draws its type.