---
title: "Install Diagrams"
description: "Install the Diagrams extension, register a Renderer and insert a first chart."
canonical_url: "https://tiptap.dev/docs/diagrams/getting-started/install"
---

# Install Diagrams

Install the Diagrams extension, register a Renderer and insert a first chart.

> **Alpha:**
>
> Diagrams is a Pro extension in alpha. The API may change in future releases. Before installing,
> set up [access to Tiptap's private npm registry](https://tiptap.dev/docs/guides/pro-extensions.md).

## Install

```bash
npm install @tiptap-pro/extension-diagrams
# and the library of each Renderer you use
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`                      |

- A Renderer draws charts with one library, such as ECharts. Register one for each library you
  install. [Renderers](https://tiptap.dev/docs/diagrams/renderers/overview.md)
- Install only the libraries of the Renderers you register.

## Entry points

The Renderers are entry points of the package, so a bundle 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 a model                              |
| `@tiptap-pro/extension-diagrams/core`                                                             | The data model, parsers and formats, and the Word writer, without Tiptap and without a DOM, for a server or 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.dev/docs/diagrams/renderers/echarts.md) | Charts drawn with ECharts                                                                                            |
| [`@tiptap-pro/extension-diagrams/d3`](https://tiptap.dev/docs/diagrams/renderers/d3.md)           | Charts drawn with d3                                                                                                 |
| [`@tiptap-pro/extension-diagrams/mermaid`](https://tiptap.dev/docs/diagrams/renderers/mermaid.md) | Charts and diagrams drawn with Mermaid                                                                               |
| [`@tiptap-pro/extension-diagrams/drawio`](https://tiptap.dev/docs/diagrams/renderers/drawio.md)   | draw\.io diagrams                                                                                                    |
| [`@tiptap-pro/extension-diagrams/bpmn`](https://tiptap.dev/docs/diagrams/renderers/bpmn.md)       | BPMN processes                                                                                                       |
| [`@tiptap-pro/extension-diagrams/pele`](https://tiptap.dev/docs/diagrams/renderers/pele.md)       | Mermaid diagrams drawn by Pele in a Web Worker, smaller than mermaid.js                                              |

## A first chart

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',
})
```

- `chartStyleRules()` returns the stylesheet the charts need.
- `TableKit` is optional. It lets a chart turn into a table and back.
- `chart-syntax` is the [chart syntax](https://tiptap.dev/docs/diagrams/data/chart-syntax.md): one row per line, cells split by `|`.
- The editor now holds a bar chart with three bars.

## A second chart from the Quick Input

1. Type `:::` in an empty paragraph to open the [Quick Input](https://tiptap.dev/docs/diagrams/data/quick-input.md).
2. Enter rows such as `Apr | 130`.
3. Press Enter on an empty last line.

## Change it

```ts
editor.commands.updateChartSpec({ spec: { type: 'line', title: 'Revenue' } })
editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } })
```

- The Chart Spec is how a chart shows its data: type, title, colors, axes.
- Both act on the selected chart.
- Every change is a [Command](https://tiptap.dev/docs/diagrams/api-reference/commands.md), so it undoes, reaches collaborators and can be called
  by a model.

## Next

- [Data](https://tiptap.dev/docs/diagrams/data/overview.md): typed rows, tables and Data Sources
- [Charts](https://tiptap.dev/docs/diagrams/charts/overview.md): types, appearance, axes, reference lines
- [Diagrams](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md): Mermaid, draw\.io and BPMN
- [Styling](https://tiptap.dev/docs/diagrams/guides/styling.md): colors, dark mode, your own classes