--- title: "Charts" description: "A chart is a chart node." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview" --- # Charts A chart is a chart node. ## Quick start ```ts editor.commands.insertFromText({ text: 'Month | Sales\nJan | 2\nFeb | 3' }) ``` [`insertFromText`](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/pasting.md#insertfromtext) reads the text the way a paste would, so these rows become a chart. The rows are written in the [Chart syntax](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/chart-syntax.md). ## More about charts | Page | Covers | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Appearance](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md) | Title, legend, colors, frame, caption, line styles, and which Renderer draws it | | [Editing in the chart](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/editing.md) | Renaming the title, axis titles, series and categories with a double click | | [Axes](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md) | Axis titles and ranges, grid and axis lines, ticks, category labels | | [Reference lines and bands](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/references.md) | Lines and bands at a value, such as a target or a range to stay in | | [Looks](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/looks.md) | Copying the colors and lines of one chart to another, or to a new one | | [Export](https://tiptap-docs.lin52025i.qzz.io/diagrams/export.md) | SVG, PNG, WebP, Word, and replacing a chart with an image | | [Size and view](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md) | Size, alignment, zoom, pan, maximize, narrow screens | ## Chart types A chart stores its type as `spec.type`. Most types read the Chart Data the same way. One column is the label column, usually the first: its cells name the rows, such as `Jan` and `Feb`. Each other column of numbers is a series, drawn as one line, one set of bars or one set of points. The last column says what a chart becomes in a [Word document](https://tiptap-docs.lin52025i.qzz.io/diagrams/export.md#word): a native Word chart that you can restyle in Word, an image, or a Word table. | Type | Reads the rows as | In a Word document | | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ | | `line`, `area`, `scatter` | A label column and one or more series | Word chart | | `bar` | The same. `spec.orientation: 'horizontal'` lays the bars on their side | Word chart | | `combo` | The same. See [Combo charts](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#combo-charts) | Word chart | | `radar` | One spoke per row, a line from the center out that the row's label names. One closed line per series | Word chart | | `pie`, `doughnut` | A label column and one series, the parts of a whole | Word chart | | `funnel` | A label per stage and one value, widest first | Image | | `gauge` | One value. `spec.range: { min, max }` sets its range, `0` to `100` by default | Image | | `treemap`, `tree` | Labels as paths and one value per row. `Europe / Germany` places Germany under Europe | Image | | `sankey`, `network` | One link per row. The label column is where the link starts, the next column where it ends, the third its weight | Image | | `matrix` | Words in a grid, see [Matrix](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#matrix) | Word table | - Not every Renderer draws every type. A Renderer that does not draw a type leaves the chart to the next one that does, see [Choosing the Renderer](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#choosing-the-renderer). - A sankey link that would close a loop is dropped. - A type you register with the [`chartTypes`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#charttypes) option is stored, offered to an AI model and drawn by any Renderer that lists it. - A type this editor does not know stays in the document unchanged. ### Combo charts A combo chart draws some series as bars and others as lines. You choose this per series, by column id: | Field | Values | | ---------------------------- | ------------------------------------------------ | | `spec.series[columnId].as` | `'bar'` (default) or `'line'` | | `spec.series[columnId].axis` | `'right'` puts the series on a second value axis | ### Matrix A `matrix` is a grid of words, such as a RACI matrix. The label column holds the tasks, each other column is a role, and each cell holds a letter. ```txt Task | Lead | Team | Board Plan | A | R | I Build | C | R | ``` Each distinct cell text gets a color from the series colors. R, A, C and I come first, in that order. The ECharts Renderer draws a matrix. A matrix cannot be written as Mermaid. ## How a chart is stored A chart's attributes hold everything needed to draw it again: | Attribute | Content | | ------------ | ------------------------------------------------------------------------------------------------------------------------- | | `data` | Chart Data: `columns` (`id`, `label`, `role` of `label` or `series`) and `rows` | | `spec` | Chart Spec, see [Chart Spec fields](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#chart-spec-fields) | | `renderer` | The id of the Renderer chosen for this chart, or `null` for the default | | `source` | The Data Source the data was read from, or `null` | | `delimiter` | The delimiter the data was typed with, so the data looks the same when you edit it as text again | | `previewUrl` | An optional image URL written into the HTML output | The document never stores the drawn chart, the size it was drawn at on screen, or its loading state. A size you set is stored in `spec.size`. ### In HTML A chart is a `
`. Its data is a ``, so the numbers survive an HTML or Markdown export and a screen reader can read them. Its title is the `
`. The Chart Spec and the Data Source are stored as JSON in `data-tt-chart-*` attributes on the `
`, see [Data attributes](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/selectors.md#data-attributes). ## Commands ### insertChart Inserts a chart at the selection, or at `pos`, and selects it. ```ts editor.commands.insertChart({ type: 'bar', data: { columns: [ { id: 'month', label: 'Month', role: 'label' }, { id: 'revenue', label: 'Revenue', role: 'series' }, ], rows: [ ['Jan', 120], ['Feb', 150], ], }, }) ``` | Option | Type | Description | | ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `ChartData` | The Chart Data | | `spec` | `Partial` | The Chart Spec. Wins over `look` where both set a field | | `type` | `ChartType` | Shortcut for `spec.type` | | `renderer` | `string \| null` | The id of the Renderer to draw with. `null` uses the default | | `source` | `ChartSource \| null` | The Data Source the chart follows | | `delimiter` | `string \| null` | The delimiter the data was typed with | | `pos` | `number` | The position to insert at. Defaults to the selection | | `look` | `ChartLook` | A saved look the chart starts with, see [`applyChartLook`](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/looks.md#applychartlook) | An empty paragraph at the selection is replaced. When a chart is selected, the new chart goes after it. ### insertChartFrom Inserts a chart written in a registered format. ```ts editor.commands.insertChartFrom({ format: 'chart-syntax', content: 'Month | Revenue\nJan | 120\nFeb | 150', }) ``` | Option | Type | Description | | ---------- | ---------------- | --------------------------------------------------------------- | | `format` | `string` | `'chart-json'`, `'chart-syntax'`, `'mermaid'`, or one you added | | `content` | `string` | The text in that format | | `type` | `ChartType` | The type, used when the content does not name one | | `renderer` | `string \| null` | The id of the Renderer to draw with | | `pos` | `number` | The position to insert at. Defaults to the selection | Returns `false` when the content cannot be read. ### importMermaidChart Inserts a chart from Mermaid chart source. ```ts editor.commands.importMermaidChart({ source: 'pie\n "Dogs" : 386\n "Cats" : 85' }) ``` | Option | Type | Description | | -------- | -------- | ---------------------------------------------------- | | `source` | `string` | The Mermaid source | | `pos` | `number` | The position to insert at. Defaults to the selection | Mermaid draws most of its kinds as diagrams. These five kinds hold numbers, so they become charts with data you can edit: | First line | Chart type | Data | | -------------- | --------------- | ------------------------------------------------------------ | | `pie` | `pie` | A row per slice | | `xychart-beta` | `bar` or `line` | A row per x-axis category, a series per bar or line | | `sankey-beta` | `sankey` | A row per flow: source, target, value | | `radar-beta` | `radar` | A row per axis, a series per curve. `min` and `max` are kept | | `treemap-beta` | `treemap` | A row per node with a value, its label the path, `A / B` | - The chart's title comes from `title`, or from frontmatter for sankey and treemap. - How Mermaid colors the chart (`classDef`, `showLegend`, `ticks`, `graticule`) is left out. - `toMermaidSource` and the `mermaid` format turn a chart back into Mermaid source. They write the same five kinds. - Mermaid's pie, radar and treemap read no minus sign, so they cannot show a value below zero. When such a chart is written back to Mermaid, a pie slice or a treemap node below zero is left out, and a radar value below zero is written as zero. Pasting Mermaid chart source runs this command, see [Pasting](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/pasting.md#how-pasted-text-is-read). Returns `false` for any other Mermaid diagram. ### convertCodeBlockToChart Replaces a code block with the chart its [Mermaid chart source](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#importmermaidchart) describes. ```ts if (editor.can().convertCodeBlockToChart()) editor.commands.convertCodeBlockToChart() ``` | Option | Type | Description | | ------ | -------- | ----------------------------------------------------------- | | `pos` | `number` | A position inside the code block. Defaults to the selection | Any node with `code: true` in its spec counts as a code block. Mod-Enter in the code block runs the command too, see [Mod-Enter in a code block](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md#mod-enter-in-a-code-block). Returns `false` for a code block holding anything else. ### insertDiagramInput Opens an empty [Quick Input](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md) at the selection, as typing the [`trigger`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#trigger) does. ```ts editor.chain().focus().insertDiagramInput({ type: 'pie' }).run() ``` | Option | Type | Description | | ------ | ----------- | -------------------------------------------------------------------------------------- | | `type` | `ChartType` | The chart type the Quick Input starts with. Defaults to the `chart.defaultType` option | Returns `false` when the schema has no `diagramInput` node.