--- title: "Editing in the diagram" description: "You can change a Mermaid diagram right where it is drawn." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing" --- # Editing in the diagram You can change a Mermaid diagram right where it is drawn. ## Text in the diagram In an editable editor, a double click on a text in a Mermaid diagram opens a text field over it. The field holds that text. - **Enter, or leaving the field,** writes the text into the source through `updateFlowDiagram`. - **Escape** closes the field without a change. - **Only the text changes.** Shapes and lines come from the source. - **A diagram drawn from a table** opens no field. Its text belongs to the table. A Diagram Renderer of your own needs [`editing`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md#editing-in-the-diagram) for this. ### What a double click edits | Kind | What a double click opens | Written as | | --------- | --------------------------------------- | --------------------------------------------------------------------- | | Flowchart | A shape | `id["text"]` at its first mention, or `label:` in `id@{ … }` | | Flowchart | The text on an edge | `-->\|"text"\|`, or `-- "text" -->` where the edge has that form | | Sequence | A participant, at the top or the bottom | `participant id as text`, declared before its first mention if needed | | Sequence | A message | The text after the colon | | State | A state | `state "text" as id`, or the first `id : text` line | | Class | A class name | `class id["text"]`. The id stays, so relations and members keep it | | Any other | A text that appears once in the source | That text, in its place | In any other kind, the extension looks for the clicked text in the source. That covers a timeline's periods and events, a kanban's columns and cards, a mind map's nodes, and a journey's or a Gantt chart's tasks and sections. The text must appear in the source exactly once, as a complete item, not as part of a longer text. An item starts at the start of a line, after a bracket, a quote, a separator such as `:` or `,`, or after `title` or `section`. It ends at a closing bracket, a quote, a separator or the end of the line. - **A text that appears twice** opens nothing. In a gitGraph, for example, a branch name appears in `branch dev` and in `checkout dev`. A double click on the branch opens no field, and both stay as they are. - **A text that Mermaid adds** to the drawn diagram, such as a count, is not in the source. It opens nothing. - **A new text with `:`, `;`, `,`, `|`, `%`, `#`, `"`, `<`, `>`, brackets or a line break** is not written in those kinds, because it would change more than the text. - **An edge without text** has nothing to double-click. Give it text in the source or with [`renameMermaidLabel`](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing.md#without-an-editor). - **Edges written as one statement**, such as `A & B --> C`, share their text. - **A straight double quote** in the text becomes a typographic one (“ ”). ## Moving shapes In an editable editor, you can drag a shape of a Mermaid flowchart to move it. - **Dragging an empty spot** next to the shapes pans a zoomed-in diagram, see [Size and view](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md). - **The offset** snaps to steps of 10 units of the diagram. - **When you let go of the pointer,** the offset is written once, through [`setDiagramNodePosition`](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing.md#setdiagramnodeposition). One undo puts the shape back. - **To put all shapes back,** call [`resetDiagramPositions`](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing.md#resetdiagrampositions). ### How moved shapes are drawn Mermaid first lays out the diagram from its source. Then the moved shapes are drawn at their offsets, in the editor and in every export. - **Lines of a moved shape** are drawn straight from border to border, with their label in the middle. - **Lines between shapes that did not move** keep their routing. - **A subgraph's frame** stays where the layout put it, even when you move a shape out of it. - **The diagram grows** when you move a shape past its edge. ### Where the offsets are kept The offsets are stored per node id in `options.positions`. - **Renaming the id** in the source loses the offset. - **An id that is gone** from the source moves nothing. - **A change of the source** keeps the offsets. - **Only flowcharts** can be moved this way. Shapes of other Mermaid kinds, and draw\.io and BPMN diagrams, cannot. A Diagram Renderer of your own needs [`nodeAt` and `movePositions`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md#editing-in-the-diagram). ## Lines in a diagram You style the lines of a Mermaid diagram in its source, with `linkStyle`. There is no field for them outside the source. ```txt flowchart LR a --> b --> c linkStyle 0 stroke-dasharray: 5 5, stroke-width: 2px ``` ## Commands ### setDiagramNodePosition Moves one shape of the selected Mermaid flowchart, or the one at `pos`, away from where the layout puts it. ```ts editor.commands.setDiagramNodePosition({ nodeId: 'ship', dx: 40, dy: 60 }) ``` | Option | Type | Description | | -------- | -------- | ----------------------------------------------------------------------- | | `nodeId` | `string` | The id the source gives the shape, such as `ship` in `ship[Shipped]` | | `dx` | `number` | The horizontal offset, in the diagram's units | | `dy` | `number` | The vertical offset, in the diagram's units. `0, 0` puts the shape back | | `pos` | `number` | The diagram's position. Defaults to the selected diagram | Returns `false` for a diagram that is not a Mermaid flowchart, for an id with a space or punctuation other than `-` and `_`, and for an offset that is not a number or is beyond 10,000. ### resetDiagramPositions Puts every moved shape back where the layout puts it. ```ts editor.commands.resetDiagramPositions() ``` | Option | Type | Description | | ------ | -------- | -------------------------------------------------------- | | `pos` | `number` | The diagram's position. Defaults to the selected diagram | Returns `false` for a diagram without moved shapes. ## Without an editor These functions from `@tiptap-pro/extension-diagrams/core` work on the source, without an editor or a drawn diagram: | Function | Returns | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `renameMermaidLabel(source, target, label)` | The source with that text replaced, every other character kept, or `null` when the source is not of the target's kind, the target is not in it, or the label is empty | | `renameMermaidNode(source, nodeId, label)` | The same as `renameMermaidLabel` with a target of kind `'node'` | | `renameMermaidText(source, text, label)` | The same with a target of kind `'text'` | | `isRenamableMermaidText(source, text)` | Whether the text appears once in the source, as a complete item, so it can be renamed | | `flowDiagramPositions(diagram)` | The offsets as `{ [nodeId]: { dx, dy } }`, leaving out entries that are not valid | ```ts import { renameMermaidLabel } from '@tiptap-pro/extension-diagrams/core' const source = renameMermaidLabel( 'flowchart LR\n A[Order] --> B{Paid?}', { kind: 'edge', id: 'L_A_B_0' }, 'placed', ) // 'flowchart LR\n A[Order] -->|"placed"| B{Paid?}' ``` `target` is `{ kind, id }`: | `kind` | `id` | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `'node'` | A flowchart shape's id | | `'edge'` | A flowchart edge's id as Mermaid gives it: `L___`, where `n` counts the edges between the same two nodes from 0 | | `'participant'`, `'state'`, `'class'` | Its id | | `'message'` | Its place among the messages, from `'0'` | | `'text'` | The text itself, in any other kind. It must appear once in the source, as a complete item |