---
title: "Chart syntax"
description: "The chart syntax is how a chart is written as text."
canonical_url: "https://tiptap.dev/docs/diagrams/data/chart-syntax"
---

# Chart syntax

The chart syntax is how a chart is written as text.

```txt
bar
Month | Online | Retail
Jan   | 42     | 30
Feb   | 48     | 28
```

## The type line

- **A first line that holds only a chart type**, `bar`, `pie` or a type registered with
  `chartTypes`, names the type, as the header of Mermaid source does. Case and the space around
  it do not matter.
- **Without it**, the chart takes the type it was given, or `chart.defaultType`.
- **It wins over a type given separately**, so the text alone says what the chart becomes.
- **It stays in the text.** `editChartAsText` writes it back as the first line, and
  `setDiagramInputType` rewrites it.

## How the rows are read

| Rule          | How it reads                                                                                |
| ------------- | ------------------------------------------------------------------------------------------- |
| Delimiters    | Comma, semicolon, pipe and tab, set with the `chart.delimiters` option                      |
| Header        | The first row is the header when it holds no number outside the first column                |
| `{H}`         | In front of a cell, marks it as a header cell explicitly                                    |
| Labels        | The first column holds the labels                                                           |
| `{L}`         | In front of a cell, marks it as a label explicitly                                          |
| Empty cell    | A missing value                                                                             |
| Not a number  | A cell that is not a number is kept as text                                                 |
| Quotes        | A cell in double quotes may contain the delimiter                                           |
| Lists         | A leading bullet or number (`•`, `-`, `*`, `1.`) is ignored, so a pasted list reads as rows |
| Single column | Lines without any delimiter are one series of values, labeled 1, 2, 3 and so on             |

### Which delimiter splits

- The first line that contains an allowed delimiter decides it for the whole block.
- On a line with several, a tab, a pipe or a semicolon wins over a comma.
- So `Jan ; 1,5` splits at the semicolon and reads `1,5` as a number.

### Numbers

- With `decimalSeparator: 'auto'`, `1.5` is read as 1.5.
- With `'auto'`, `1,5` is read as 1.5 too, when the delimiter is not a comma.
- Set `decimalSeparator` to `'.'` or `','` to fix the decimal separator.
- Thousands separators are not read.

### Errors

- A quote that is opened and never closed is an error on that line.
- An error names the line, for example `Line 3: A quote is opened and never closed.`

## In code

The same text works without the box, through `insertChartFrom`, `updateChartFrom` and the
tools for a model:

```ts
editor.commands.insertChartFrom({ format: 'chart-syntax', content: 'bar\nJan | 42\nFeb | 48' })
```

`editor.storage.diagrams.read({ format: 'chart-syntax' })` writes a chart's data in the chart syntax,
with the delimiter it was typed with.

| Delimiter | Written as                  |
| --------- | --------------------------- |
| Pipe      | `\|`                        |
| Tab       | A bare tab                  |
| Any other | The delimiter, then a space |