--- title: "Install Diagrams" description: "Install the Diagrams extension, register a Renderer and insert a first chart." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/getting-started/install" --- # Install Diagrams Install the Diagrams extension, register a Renderer and insert a first chart. > **Alpha:** > > Diagrams is in alpha and available through a pilot program. The API may change in future releases. ## Install 1. [Contact our team](https://tiptap.dev/contact-sales?form=pilot-program) to join the Tiptap Diagrams pilot program. 2. Configure your package manager by following the [private registry guide](https://tiptap-docs.lin52025i.qzz.io/guides/pro-extensions.md). 3. Install the package and the library of each Renderer you use: ```bash npm install @tiptap-pro/extension-diagrams npm install echarts ``` | Package | Kind | Version | | ---------------------------- | ------------------------ | ------------------------------------ | | `@tiptap/core`, `@tiptap/pm` | Peer dependency | 3.31 or later | | `echarts` | Optional peer dependency | `^6.0.0` | | `d3` | Optional peer dependency | `^7.9.0` | | `d3-sankey` | Optional peer dependency | `^0.12.3`, for sankey charts with D3 | | `mermaid` | Optional peer dependency | `>=11.16.1 <12` | | `pele` | Optional peer dependency | `1.6.0`, for the Pele Renderer | The examples below also use `@tiptap/starter-kit` and `@tiptap/extension-table`. Install them too if your editor does not have them yet. The draw\.io and BPMN Renderers load their library from a file you serve. See [draw.io](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/drawio.md) and [BPMN](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/bpmn.md). [Renderers](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview.md) lists every Renderer. ## A first chart In the demo, write rows as text, insert them as a chart, then change its type: > **Interactive demo:** [DiagramsInsertChart](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsInsertChart) ```ts import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import { TableKit } from '@tiptap/extension-table' import { Diagrams, chartStyleRules } from '@tiptap-pro/extension-diagrams' import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts' const style = document.createElement('style') style.textContent = chartStyleRules() document.head.append(style) const editor = new Editor({ element: document.querySelector('#editor'), extensions: [ StarterKit, TableKit, Diagrams.configure({ renderers: [echartsRenderer()], chart: { defaultType: 'bar' }, }), ], }) editor.commands.insertChartFrom({ format: 'chart-syntax', content: 'Month | Revenue\nJan | 120\nFeb | 150\nMar | 110', }) ``` The editor now holds a bar chart with three bars, and the chart is selected. - `chartStyleRules()` returns the stylesheet the charts need. - `TableKit` is optional. With it, you can turn a chart into a table and back. - `chart: { defaultType: 'bar' }` gives a new chart the type `bar`. See [`defaultType`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#defaulttype). - `chart-syntax` is the [Chart syntax](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/chart-syntax.md): one row per line, with the cells separated by `|`. ## Change it `updateChartSpec` and `updateChartAxis` change the selected chart, such as the one [A first chart](#a-first-chart) inserts: ```ts editor.commands.updateChartSpec({ spec: { type: 'line', title: 'Revenue' } }) editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } }) ``` The Chart Spec holds how a chart shows its data: type, title, colors and axes. Without a selected chart, both commands return `false`. Every change is a [command](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/commands.md), so the user can undo it and collaborators receive it. An AI model calls them through [tools](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai.md). ## A second chart from the Quick Input 1. Type `:::` in an empty paragraph to open the [Quick Input](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md), a text field inside the document. 2. Enter rows such as `Apr | 130`. 3. Press Enter on an empty last line. ## A first diagram A flow diagram needs a Diagram Renderer. The one for Mermaid, a library that draws diagrams from text, needs `mermaid`: ```bash npm install mermaid@11 ``` This is the editor from [A first chart](#a-first-chart) with the Mermaid Diagram Renderer and the diagram styles, inserting a flowchart: ```ts import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import { TableKit } from '@tiptap/extension-table' import { Diagrams, chartStyleRules, flowDiagramStyleRules } from '@tiptap-pro/extension-diagrams' import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts' import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid' import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline' import mermaidUrl from 'mermaid/dist/mermaid.min.js?url' const style = document.createElement('style') style.textContent = chartStyleRules() + flowDiagramStyleRules() document.head.append(style) const editor = new Editor({ element: document.querySelector('#editor'), extensions: [ StarterKit, TableKit, Diagrams.configure({ renderers: [echartsRenderer()], diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })], chart: { defaultType: 'bar' }, }), ], }) editor.commands.insertFlowDiagram({ source: 'flowchart LR\n order[Order placed] --> ship[Shipped]', title: 'Order flow', }) ``` The editor shows a flowchart with two boxes, and the diagram is selected. Mermaid draws in a sandboxed iframe from two files your bundler serves: `mermaidUrl` is Mermaid, `rendererUrl` the script that draws with it. In Vite, `?url` gives a file's URL, and `no-inline` keeps a small file from becoming a data URL, which the iframe cannot load. The [Mermaid Renderer](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#quick-start) covers other bundlers. ## Entry points Each Renderer is its own entry point of the package. Your bundle then holds only the libraries you use. | Import from | What it holds | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `@tiptap-pro/extension-diagrams` | `Diagrams`, its nodes and commands, Data Sources, export, styling and tools for an AI model | | `@tiptap-pro/extension-diagrams/core` | The chart data types, parsers and formats, and the Word writer. It needs no Tiptap and no DOM, so it runs on a server or in a worker | | `@tiptap-pro/extension-diagrams/export` | Turning an SVG into a PNG, WebP or a download, in the browser | | `@tiptap-pro/extension-diagrams/theme` | Reading chart and diagram colors from CSS custom properties, in the browser | | [`@tiptap-pro/extension-diagrams/echarts`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md) | Charts drawn with ECharts | | [`@tiptap-pro/extension-diagrams/d3`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md) | Charts drawn with D3 | | [`@tiptap-pro/extension-diagrams/mermaid`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md) | Charts and diagrams drawn with Mermaid | | [`@tiptap-pro/extension-diagrams/drawio`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/drawio.md) | draw\.io diagrams | | [`@tiptap-pro/extension-diagrams/bpmn`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/bpmn.md) | BPMN process models | | [`@tiptap-pro/extension-diagrams/pele`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/pele.md) | Mermaid diagrams drawn by Pele in a Web Worker. Pele is smaller than mermaid.js | ## Next - [Data](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/overview.md): typed rows, tables and Data Sources - [Charts](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md): types, appearance, axes, reference lines - [Diagrams](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md): Mermaid, draw\.io and BPMN - [Styling](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/styling.md): colors, dark mode, your own classes