---
title: "Chart syntax"
description: "The Chart syntax is a short way to write a chart as text."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/data/chart-syntax"
---

# Chart syntax

The Chart syntax is a short way to write a chart 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, such as `bar`, `pie` or a type registered with
`chartTypes`, is the type line. Case and spaces around it do not matter.

- **Without a type line**, the chart takes the type you pass to the command, such as the `type`
  option of `insertChartFrom`. Without one, it takes `chart.defaultType`.
- **The type line wins** over the `type` option, so the text alone says what the chart becomes.
- **The type line 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                                               |
| Labels        | The first column holds the labels                                                           |
| `{L}`         | In front of a cell, marks it as a label                                                     |
| 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             |

So `Month | Sales` is a header and `Jan | 2` is a data row. For a header that holds numbers,
such as `Region | 2025 | 2026`, put `{H}` in front of its cells.

### Which delimiter splits

The first line that contains an allowed delimiter decides the delimiter for the whole text. On a
line with several delimiters, 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, and so is `1,5` 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 its line, for example
`Line 3: A quote is opened and never closed.`

## In code

`insertChartFrom`, `updateChartFrom` and the [tools for an AI model](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/ai.md) take the same
text:

```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 |