--- title: "Export" description: "A chart or a diagram as an SVG, PNG, WebP or JPEG file, every chart in a Word document, or a chart replaced by an image of it." canonical_url: "https://tiptap.dev/docs/diagrams/export" --- # Export A chart or a diagram as an SVG, PNG, WebP or JPEG file, every chart in a Word document, or a chart replaced by an image of it. ## Files ```ts import { downloadBlob } from '@tiptap-pro/extension-diagrams/export' const { blob, svg, width, height, alt } = await editor.storage.diagrams.export( { pos }, { format: 'png', scale: 2, background: '#ffffff' }, ) downloadBlob(blob, 'chart.png') ``` ### What to export The first argument, `target`, is one of: | Target | Exports | | --------------------------- | ------------------------------------ | | `{ pos? }` | A chart or a diagram in the document | | `{ data, spec, renderer? }` | Chart data that is in no document | - **A diagram** is drawn by its Diagram Renderer. - **`renderer` and `size`** do not apply to a diagram. - **A diagram's theme** comes from the `--tt-flow-diagram-*` properties. ### Options | Option | Type | Default | Description | | ------------ | ------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------- | | `format` | `'svg' \| 'png' \| 'webp' \| 'jpeg'` | `'svg'` | The file format | | `scale` | `number` | `2` | Pixels per SVG unit for an image | | `background` | `string \| null` | `null` | A fill behind the chart | | `renderer` | `string` | The chart's | Draw with another Renderer | | `theme` | `ChartTheme` | The page's | A `ChartTheme` instead of the custom properties on the page | | `size` | `{ width: number; height: number }` | `{ width: 800, height: 450 }`, or 800 wide at the chart's own `ratio` | The size to draw at | | `scheme` | `'light' \| 'dark'` | `'light'` | The color scheme to draw in, whatever the page shows | ### What comes back | Field | Content | | ----------------- | ------------------------------------------------- | | `blob` | The file | | `svg` | The SVG, with concrete colors | | `width`, `height` | The size of the drawing | | `alt` | The title and description, for an `alt` attribute | | `renderer` | The Renderer it was drawn with | | `raster` | `true` when the Renderer drew pixels | - **The SVG carries concrete colors**, not `var(…)`, so it looks the same outside the page. - **A Renderer that draws pixels**, such as one on a canvas, is exported too. Its SVG holds the picture rather than shapes, so it does not scale without loss. See [Your own Renderer](https://tiptap.dev/docs/diagrams/renderers/custom.md#members). - **Image formats** need a browser. - **The SVG of ECharts and d3** can be made on a server. `@tiptap-pro/extension-diagrams/export` also has `svgToBlob`, `svgToImage`, `toDataUrl`, `readSvgSize`, `inlineSvgStyles` and `rasterToSvg`. ## Word ```ts 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) ``` | Option | Type | Description | | -------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `targets` | `ChartTarget[]` | The charts and diagrams to write, in order | | `title` | `string` | A heading above the charts | | `fallbackFont` | `string` | The font Word draws when it lacks the page's. Default `'Arial'` | | `images` | `'auto' \| 'always'` | When a chart becomes a picture, see [Charts as pictures](https://tiptap.dev/docs/diagrams/export.md#charts-as-pictures) | ### What the file holds - **One native Word chart per target**, in order, each with its data in an embedded workbook, so Word can restyle the chart and open "Edit data". - **A diagram** becomes a PNG picture, scaled to the page width, with its title as caption. - **Without `targets`**, every chart that has data and every diagram that has source, in document order. - **With none of them**, the promise rejects. - **A chart with `caption`** is followed by its description in Word's Caption style. - **Every chart and picture** carries its title and description as alt text. - **A `matrix`** becomes a Word table with shaded cells. - **Series colors and the font** come from the page; see [Styling](https://tiptap.dev/docs/diagrams/guides/styling.md). - **Only the charts and diagrams** are in the file, not the rest of the document. ### Charts as pictures | `images` | What a chart becomes | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `'always'` | A PNG picture, drawn by its Renderer, at the chart's size | | `'auto'` | A Word chart or Word table. A picture for a type Word has no form for, and for a chart Word's own would show differently in what it says | | Left out | The [`docxImages`](https://tiptap.dev/docs/diagrams/api-reference/options.md#docximages) option decides | - **A chart Word's own would show differently** is a scatter chart with numbers on its x axis, which Word would space evenly. - **A chart no Renderer can draw as a picture** stays a Word chart, with a note. ### Notes `notes` says what Word shows differently from the editor, one sentence each. It is known from the data and the spec before the file is opened. A note has `pos`, `title` and `message`. Notes cover: - a font Word lacks (`pos: null`), - a pie with more than one series, - the range of the x axis, - a color that is not a hex value, - options only one Renderer understands, - that a linked chart holds a snapshot in Word, - a chart written as a picture, and why when its type has a Word form, - a diagram, which is a picture in Word, or was left out when it could not be drawn. ### Without exporting These come from `@tiptap-pro/extension-diagrams/core`: | Function | Returns | | ---------------------------------------------------------- | --------------------------------------------------------- | | `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 same list as `notes`, for one chart | ## A whole document A converter that does not know the `chart` and `flowDiagram` Nodes leaves them out. `toPortableContent` from `@tiptap-pro/extension-diagrams/core` returns a copy of the document in which they are made of Nodes every converter knows. Export that copy instead, here with `@tiptap-pro/extension-export-docx`, which sends it to Tiptap's Convert service: ```ts 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() }) ``` - **`toPortableContent` needs no browser.** It runs on a server too. - **`CONVERT_TOKEN`** is your Convert API token. See the export-docx docs for its options. ### What the copy holds | In the document | In the copy | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A chart | Its picture, when there is one, and its data as a table. Its title above a table without a picture; its description below, when the chart shows it as a caption | | A chart hidden behind the table it follows | Nothing; the table is already there | | A diagram | Its picture, when `imageFor` gives one; otherwise its title and its source as code-formatted lines | | An open Quick Input | Its text as code-formatted lines | - **A chart has a picture** only when your integration uploads one (`uploadImage`, which sets `previewUrl`). Without it, the copy holds its data as a table. - **A matrix cell's color** is its `background` attribute, and its text color a `textStyle` mark. A converter that reads them keeps the colors. ### Options | Option | Value | Default | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `charts` | `'both'`, `'image'` (the picture, or the table when there is none), `'table'` or `'native'` (see [Native Word charts](https://tiptap.dev/docs/diagrams/export.md#native-word-charts)) | `'both'` | | `imageFor` | `(figure) => url \| null`, the picture of a chart or a diagram; `figure` is `{ kind, attrs }` | A chart's `previewUrl` | | `sources` | `'paragraphs'`, one code-formatted paragraph per line, or `'codeBlock'` | `'paragraphs'` | | `names` | Your Node names for `table`, `tableRow`, `tableHeader`, `tableCell`, `paragraph`, `image`, `codeBlock` | StarterKit's and `@tiptap/extension-table`'s | | `decimalSeparator` | `'.'` or `','` for numbers in a table | `'.'` | `'paragraphs'` keeps a diagram's source in a converter that leaves out code blocks. Choose `'codeBlock'` for a converter that writes them, such as one to Markdown or HTML. ### Native Word charts With `charts: 'native'`, a chart of a type Word draws itself (bar, line, area, scatter, pie and their kin) becomes a marker line instead of a picture and a table. After any converter wrote the Word file, `addNativeCharts` replaces each marker with a native Word chart, which the reader can restyle and whose data opens in Excel ("Edit data"). ```ts 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 }) ``` - **Other types** are written as with `'both'`. - **Pass `addNativeCharts` the same document** you passed `toPortableContent`; it finds the charts in the same order. - **`theme` and `fallbackFont`** are taken by `addNativeCharts` as by `exportDocx` of the storage. - **A marker a converter split or changed** is left as text. ## Commands ### convertChartToImage Replaces a chart with an image of it, through the image Node named by the option `imageNodeName`. ```ts editor.commands.convertChartToImage({ format: 'svg', keepData: true }) ``` | Option | Type | Description | | ---------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | `'svg' \| 'png' \| 'webp' \| 'jpeg'` | The image format. Default `'png'` | | `keepData` | `boolean` | The image keeps the chart, so [`convertImageToChart`](https://tiptap.dev/docs/diagrams/export.md#convertimagetochart) brings it back. Kept unless `false` | | `pos` | `number` | The chart's position. Defaults to the selected chart | - **The image is uploaded** with `uploadImage`, or embedded as a data URL without it. - **The chart is replaced** once the image is ready, unless it changed in the meantime. - **The image is exported at twice its size**, so it stays sharp on high-density screens. - **When the image Node has a `width` attribute**, as `@tiptap/extension-image` does, the command sets it to the chart's width, and the image shows at that size. Give images `max-width: 100%` so they shrink on a narrow screen: ```css .tiptap img { max-width: 100%; height: auto; } ``` ### convertImageToChart Turns an image made with `keepData` back into the chart. ```ts editor.commands.convertImageToChart() ``` | Option | Type | Description | | ------ | -------- | ---------------------------------------------------- | | `pos` | `number` | The image's position. Defaults to the selected image | ### redrawChartImage Draws an image made with `keepData` again from the chart it keeps, with the current styles, Renderers and color scheme. ```ts editor.commands.redrawChartImage({ pos }) ``` | Option | Type | Description | | -------- | ------------------------------------ | ---------------------------------------------------- | | `format` | `'svg' \| 'png' \| 'webp' \| 'jpeg'` | The image format. Default `'png'` | | `pos` | `number` | The image's position. Defaults to the selected image | - **The image keeps** its other attributes and the chart it keeps. - **Only its file, text and width change**, once the new file is ready, unless the image changed in the meantime. Returns `false` for an image that keeps no chart, and when no Renderer draws its type.