Quick Input

The Quick Input is a text field inside the document where the user writes a chart or a diagram as text. Typing ::: in an empty paragraph opens it, and when the user confirms it, the text becomes a chart or a diagram.
New tab

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

Mermaid, 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:

TextBecomes
Rows, with an optional type line such as barA chart, see Writing a chart
A Mermaid chart: pie, xychart, sankey, radar-beta or treemapA chart, with the type and title of its header
Any other Mermaid diagram, draw.io XML or BPMN XMLA 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:

New tab

Keys in the Quick Input

Mod is Cmd on macOS and Ctrl on other systems.

KeyIn the Quick Input
EnterA new line. On an empty last line, draws the chart or the diagram
Shift-EnterA new line, also on an empty last line
Mod-Enter, EscapeDraws the chart or the diagram
Mod-Shift-ASelects everything typed into the Quick Input
Mod-AStill selects the whole document
BackspaceIn 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 confirmDiagramInput returns false. 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 InputMessage
A word where a number belongs, such as Mar, manyLine 3: "many" is not a number.
A quote that is opened and never closedLine 2: A quote is opened and never closed.
A Mermaid chart with a line Mermaid does not readLine 2: expected a slice such as "Label" : 42.
A Mermaid diagram with only its header, flowchart LRA Mermaid flowchart diagram needs more than its first line.
draw.io XML or BPMN XML that is cut off or not a diagramThis draw.io XML cannot be read.
A diagram, in an editor without the flowDiagram nodeThis 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 pie or sankey-beta, becomes a chart, as with convertCodeBlockToChart.
  • 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()
OptionTypeDefaultDescription
posnumberThe selectionA 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')
ParameterTypeDescription
typeChartTypeA 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')
ParameterTypeDescription
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(';')
ParameterTypeDescription
delimiterstring | nullOne 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()
OptionTypeDefaultDescription
posnumberThe selected chartThe 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()
OptionTypeDefaultDescription
posnumberThe selected diagramThe 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()
OptionTypeDefaultDescription
posnumberThe selected chartThe chart's position

Returns false without a chart, for a read-only chart, or without the table nodes.