--- title: "Charts" description: "A chart is a chart Node that holds its data (Chart Data) and how to show it (Chart Spec)." canonical_url: "https://tiptap.dev/docs/diagrams/charts/overview" --- # Charts A chart is a chart Node that holds its data (Chart Data) and how to show it (Chart Spec). ## Quick start ```ts editor.commands.insertFromText({ text: 'Month | Sales\nJan | 2\nFeb | 3' }) ``` - [`insertFromText`](https://tiptap.dev/docs/diagrams/data/pasting.md#insertfromtext) reads the text as a paste would. Rows become a chart. - The rows are written in the [chart syntax](https://tiptap.dev/docs/diagrams/data/quick-input.md#writing-a-chart). ## More about charts Each page beside this one covers one part of the Chart Spec. | Page | Covers | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [Appearance](https://tiptap.dev/docs/diagrams/charts/appearance.md) | Title, colors, frame, caption, series line styles, the Renderer | | [Editing in the picture](https://tiptap.dev/docs/diagrams/charts/editing.md) | Renaming the title, axis titles, series and categories with a double click | | [Axes](https://tiptap.dev/docs/diagrams/charts/axes.md) | Axis titles and ranges, grid and axis lines, ticks, category labels | | [Reference lines and bands](https://tiptap.dev/docs/diagrams/charts/references.md) | Reference lines and bands, such as a target or a range to stay in | | [Looks](https://tiptap.dev/docs/diagrams/charts/looks.md) | Taking the look of one chart to another, or to a new one | | [Export](https://tiptap.dev/docs/diagrams/export.md) | SVG, PNG, WebP, Word, and replacing a chart with an image | | [Size and view](https://tiptap.dev/docs/diagrams/guides/size-and-view.md) | Size, alignment, zoom, pan, maximize, narrow screens | ## Chart types A chart stores its type as `spec.type`. Each type reads the same rows in one of these ways: | Type | Reads | 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.dev/docs/diagrams/charts/overview.md#combo-charts) | Word chart | | `radar` | A label per spoke, a 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 | Picture | | `gauge` | One value. `spec.range: { min, max }` sets its range, `0` to `100` by default | Picture | | `treemap`, `tree` | Labels as paths and one value per row. `Europe / Germany` places Germany under Europe | Picture | | `sankey`, `network` | One link per row: the label column is the source, the next column the target, the one after it the weight | Picture | | `matrix` | Words in a grid, see [Matrix](https://tiptap.dev/docs/diagrams/charts/overview.md#matrix) | Word table | - **A Renderer without the type** leaves the chart to the next Renderer that has it. Not every Renderer draws every type. - **A sankey link that would close a loop** is dropped. - **A type you register** with the [`chartTypes`](https://tiptap.dev/docs/diagrams/api-reference/options.md#charttypes) option is stored, offered to a model and drawn by any Renderer that lists it. - **A type this editor does not know** is kept in the document, unchanged. ### Combo charts | Field | Values | | ---------------------------- | ------------------------------------------------ | | `spec.series[columnId].as` | `'bar'` (default) or `'line'` | | `spec.series[columnId].axis` | `'right'` puts the series on a second value axis | ### Matrix `matrix` is a grid of words such as a RACI matrix: the tasks in the label column, a column per role and a letter in each cell. ```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. - A matrix is drawn by the ECharts Renderer. - A matrix cannot be written as Mermaid. - In a Word document, a matrix is a table with shaded cells. ## 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: `type`, `title`, `description`, `legend`, `palette`, `axes`, `references`, `stacked`, `innerRadius`, `orientation`, `range`, `series`, and `renderer` for options a single Renderer understands | | `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 it is shown the same way when edited as text | | `previewUrl` | An optional image URL written into the HTML output | The drawn picture, its size and its loading state are never stored. ### In HTML - A chart is a `
`. - Its data is a ``, so the numbers survive an HTML or Markdown export and are read by a screen reader. - Its title is the `
`. - The spec and the source travel in `data-tt-chart-*` 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.dev/docs/diagrams/charts/looks.md#applychartlook) | - An empty paragraph at the selection is replaced. - With a chart selected, the new one 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 say | | `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 | These Mermaid kinds are charts: | 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`, `max` kept | | `treemap-beta` | `treemap` | A row per node with a value, its label the path, `A / B` | - **A title** comes from `title`, or from frontmatter for sankey and treemap. - **How Mermaid colors it** (`classDef`, `showLegend`, `ticks`, `graticule`) is left out. - **Back to Mermaid**, `toMermaidSource` and the `mermaid` format write the same kinds. - **A value below zero** has no place in Mermaid's pie, radar and treemap, which read no minus sign. Written back, a pie slice or a treemap node below zero is left out, and a radar value is written as zero. Pasting Mermaid chart source calls it, when the source is: - bare: one of these kinds on the first line and at least one data row, - in a ` ```mermaid ` fence, - or a code block with the language `mermaid`. Pasting into a code block keeps the text. Returns `false` for any other Mermaid diagram. ### convertCodeBlockToChart Replaces a code block with the chart its [Mermaid chart source](https://tiptap.dev/docs/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. - `editor.can().convertCodeBlockToChart()` says whether to offer it. - Mod-Enter in the code block runs it too, unless [`codeBlockShortcut`](https://tiptap.dev/docs/diagrams/api-reference/options.md#codeblockshortcut) says otherwise. Returns `false` for a code block holding anything else. ### insertDiagramInput Opens an empty [Quick Input](https://tiptap.dev/docs/diagrams/data/quick-input.md) at the selection, as typing the trigger does. ```ts editor.chain().focus().insertDiagramInput({ type: 'pie' }).run() ``` | Option | Type | Description | | ------ | ----------- | --------------------------- | | `type` | `ChartType` | The chart type the box gets |