Quick start
The Diagrams extension adds the Quick Input as a node named diagramInput, so ::: works in
the editor from A first chart without more setup. A button
of your own, here one with the id new-chart, opens it in that editor with
insertDiagramInput:
document.querySelector('#new-chart')?.addEventListener('click', () => {
editor.chain().focus().insertDiagramInput({ type: 'bar' }).run()
})The user writes rows and presses Enter on an empty last line, and the rows become a bar chart:
Month | Online | Retail
Jan | 42 | 30Mermaid, a language for diagrams as text, needs a
Diagram Renderer. The trigger
option sets another opening text. Diagrams.configure({ chart: false }) leaves out charts and,
with them, the Quick Input.
What the text becomes
The Quick Input reads text with the rules of a paste, and also makes a chart from rows:
| Text | Becomes |
|---|---|
Rows, with an optional type line such as bar | A chart, see Writing a chart |
A Mermaid chart: pie, xychart, sankey, radar-beta or treemap | A chart, with the type and title of its header |
| Any other Mermaid diagram, draw.io XML or BPMN XML | A diagram |
pie above rows such as Dogs, 3 is a type line, because Mermaid writes a pie's rows as
"Dogs" : 3. xychart, sankey and treemap may also end in -beta.
Writing a chart
A chart is written in the Chart syntax.
Writing a diagram
A diagram is written in its own language and kept as typed. Mermaid names the kind of diagram on its first line, see Flow diagrams. draw.io and BPMN XML are pasted, see draw.io and BPMN.
Back into text
editChartAsText and editDiagramAsText open a chart or a Mermaid diagram in the Quick Input
again. When the user changes the first line, a chart becomes another chart type, or a diagram.
In the demo, open a chart as text, then write flowchart LR and a line such as A --> B:
Keys in the Quick Input
Mod is Cmd on macOS and Ctrl on other systems.
| Key | In the Quick Input |
|---|---|
| Enter | A new line. On an empty last line, draws the chart or the diagram |
| Shift-Enter | A new line, also on an empty last line |
| Mod-Enter, Escape | Draws the chart or the diagram |
| Mod-Shift-A | Selects everything typed into the Quick Input |
| Mod-A | Still selects the whole document |
| Backspace | In an empty Quick Input, closes it. Not in one opened from a chart |
Enter after a lone type name, such as pie, keeps it as the type line, and the Quick Input shows
example rows for that type until the user types a row.
When the user renames a text inside a drawn chart or diagram, such as a title, Escape instead closes that field and drops the change.
When the Quick Input closes
- Moving the selection out of the Quick Input draws it, as confirming does.
- An empty Quick Input becomes an empty paragraph.
- Text that cannot be read, such as an unclosed quote, keeps the Quick Input open, and
confirmDiagramInputreturnsfalse. The Quick Input then shows why, below the text, until the user changes the text, the type or the delimiter.
When the text cannot be read
The message names the line of the Quick Input it is about, counting the type line and empty lines:
| Text in the Quick Input | Message |
|---|---|
A word where a number belongs, such as Mar, many | Line 3: "many" is not a number. |
| A quote that is opened and never closed | Line 2: A quote is opened and never closed. |
| A Mermaid chart with a line Mermaid does not read | Line 2: expected a slice such as "Label" : 42. |
A Mermaid diagram with only its header, flowchart LR | A Mermaid flowchart diagram needs more than its first line. |
| draw.io XML or BPMN XML that is cut off or not a diagram | This draw.io XML cannot be read. |
A diagram, in an editor without the flowDiagram node | This editor shows charts only, no diagrams. |
Words are fine in a matrix, such as a RACI matrix, and in the source and target columns of a
sankey or network chart. Their third column, the weight, needs numbers.
The message is a span.tiptap-diagram-input-error with role="alert", so a screen reader reads
it out. The Quick Input gets aria-invalid="true", aria-describedby pointing at the message,
and data-tt-diagram-input-error with the message. Style them as in
Classes, data attributes and custom properties.
The message is never part of the document: it is not in getJSON(), in getHTML() or in
Tiptap Collaboration.
Mod-Enter in a code block
Mod-Enter in a code block turns its source into a chart or a diagram:
- Mermaid chart source, such as
pieorsankey-beta, becomes a chart, as withconvertCodeBlockToChart. - Other Mermaid source becomes a diagram, as with
convertCodeBlockToDiagram. - In any other code block, the key does what the editor otherwise binds it to.
Any node with code: true in its spec counts as a code block. The
codeBlockShortcut option sets another key for code blocks,
or false for none. It does not change the Quick Input, which always confirms with Mod-Enter.
Commands
A toolbar of your own drives the Quick Input with these.
confirmDiagramInput
Turns the open Quick Input into a chart or a diagram, also when it is shown as a table with
setDiagramInputView.
editor.commands.confirmDiagramInput()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selection | A position inside the input |
detectDiagramInput decides what the text becomes. Diagram
source becomes a diagram only with the flowDiagram node, which Diagrams adds unless you set
flowDiagram: false.
Returns false without an open input, or when the text cannot be read. In that case the Quick
Input shows why.
editor.can().confirmDiagramInput() is true whenever an input is open.
setDiagramInputType
Sets the chart type the open input becomes, and rewrites a type line already there.
editor.commands.setDiagramInputType('bar')| Parameter | Type | Description |
|---|---|---|
type | ChartType | A built-in type or one registered with chartTypes |
Returns false for an unknown type, or without an open input.
setDiagramInputView
Switches the open input between the text field and a table, and keeps what the user typed.
editor.commands.setDiagramInputView('table')| Parameter | Type | Description |
|---|---|---|
view | 'chart-syntax' | 'table' | The text field, or a table to fill in |
The table view needs the nodes table, tableRow, tableCell and tableHeader, which
TableKit adds.
Returns true when the input already shows that view. Returns false without an open input,
for 'table' without the table nodes, or when the typed text cannot be read.
setDiagramInputDelimiter
Makes the open Quick Input split its text at one configured delimiter, instead of the one it finds.
editor.commands.setDiagramInputDelimiter(';')| Parameter | Type | Description |
|---|---|---|
delimiter | string | null | One of chart.delimiters. null finds it again |
The choice lasts while the Quick Input is open. The chart keeps it, and uses it when the chart is written back as text.
Returns false without an open Quick Input in its text view, or for a delimiter not configured.
editChartAsText
Turns a chart into a Quick Input with its type line and its data in the Chart syntax.
editor.commands.editChartAsText()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selected chart | The chart's position |
On confirm, the chart gets back its Chart Spec, its Renderer and its Data Source.
Returns false without a chart, for a chart whose linked Data Source is read-only, or without
the diagramInput node.
editDiagramAsText
Turns a Mermaid diagram into a Quick Input that holds its source.
editor.commands.editDiagramAsText()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selected diagram | The diagram's position |
On confirm, rows below a type line make it a chart. A diagram that keeps its kind gets back its title, description, node positions and view.
Returns false without a diagram, for draw.io and BPMN, for a diagram drawn from a table, and
for Mermaid of a kind the extension does not know.
editChartAsTable
Turns a chart into a table of its data. When the selection leaves the table, it becomes a chart again.
editor.commands.editChartAsTable()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selected chart | The chart's position |
Returns false without a chart, for a read-only chart, or without the table nodes.