Skip to content
Mermaid Studio Logo Mermaid Studio
New Mermaid Studio Core — free Mermaid diagram support in JetBrains IDEs — Install now →

Edit Mode

Last updated:

Edit Mode transforms the live preview from a passive display into an interactive canvas. You can select, move, connect, and delete diagram elements visually, and every change is written back to the source code automatically.

Edit mode with a selected node, add handle, and the Style Pane

Enabling Edit Mode

Section titled “Enabling Edit Mode”

Click the Edit Mode toggle (pencil icon) in the preview toolbar to switch between edit mode and preview mode.

Preview toolbar

The toolbar buttons, from left to right:

  1. Add Node — Open the shape picker to insert a new node
  2. Add Subgraph — Insert a new subgraph container
  3. Theme — Set the Mermaid theme (Auto, Default, Dark, Forest, Neutral, Base)
  4. Look — Set the rendering style (Auto, Classic, Hand Drawn)
  5. Layout — Set the layout algorithm (dagre, elk, etc.)
  6. Background — Set the preview background color
  7. Edit Mode — Toggle edit mode on or off (pencil icon)
  8. Pan Mode — Toggle left-click panning (hand icon)
  9. Caret Tracking — Sync editor cursor with preview highlighting
  10. Diagram Documentation — Open Mermaid.js docs for the current diagram type

When edit mode is active, a dot grid background appears behind the diagram to indicate you are in editing mode.

In preview mode (edit mode off), the diagram behaves like a standard Mermaid render. Built-in Mermaid interactivity such as actor menus and external links works normally, and you can navigate to source by holding Command Control and clicking an element.

In edit mode, clicking an element navigates directly to its source declaration without needing a modifier key. All of the selection, manipulation, and creation features described below become available.

Pan Mode

Section titled “Pan Mode”

Click the Pan Mode toggle in the preview toolbar to switch between selection and panning.

When pan mode is active, left-click dragging pans the viewport instead of selecting elements. You can still click individual elements to select them.

Middle-click dragging always pans the diagram regardless of whether pan mode is enabled.

Caret Tracking

Section titled “Caret Tracking”

Click the Caret Tracking toggle (autoscroll icon) in the preview toolbar to link cursor movement in the editor with element highlighting in the preview.

When caret tracking is enabled, moving the cursor to a diagram element in the source code highlights the corresponding element in the preview and updates the Style Pane.

Caret tracking is off by default for .mmd files and can be toggled as needed. In Markdown files, caret tracking is always active.

Section titled “Navigation”

Edit mode provides bidirectional navigation between the source code and the rendered diagram.

  • Preview to source: Click an element in the preview to jump to its declaration in the editor. In preview mode (edit mode off), hold Command Control and click instead.
  • Hover highlighting: Navigable elements highlight when you hover over them, giving visual feedback about what you can interact with.

Selection

Section titled “Selection”

Single Selection

Section titled “Single Selection”

Click an element in the preview to select it. The selected element is highlighted, and its source range is selected in the editor.

Multi-Selection

Section titled “Multi-Selection”

Build up a selection of multiple elements using any of these methods:

  • Shift+Click an element to add or remove it from the current selection.
  • Marquee select: Click and drag on an empty area of the canvas to draw a selection rectangle around multiple elements.

Marquee selection around diagram elements

Selection Commands

Section titled “Selection Commands”

Use keyboard shortcuts to select groups of related elements:

  • Command + A Control + A selects all elements in the diagram.
  • Alt + Shift + P Alt + Shift + P selects the parent subgraph of the currently selected element.
  • Alt + Shift + C Alt + Shift + C selects all children of the currently selected subgraph.
  • Alt + Shift + S Alt + Shift + S selects all siblings at the same level as the current selection.

When multiple elements are selected, the Style Pane displays only the properties common to all selected elements.

Two nodes selected with shared style properties in the Style Pane

Adding Elements

Section titled “Adding Elements”

Add Node

Section titled “Add Node”

Click the Add Node button in the toolbar to open the shape picker. The picker is organized into tabs (Basic, Process, Technical) showing the available node shapes with visual previews.

Shape picker with Basic, Process, and Technical tabs

Select a shape to insert a new node into the diagram source. The editor caret moves to the new node so you can immediately type its label.

Add Subgraph

Section titled “Add Subgraph”

Click the Add Subgraph button in the toolbar to insert a new subgraph container into the diagram source.

Both actions are only available when edit mode is enabled.

Drag to Add with Shape

Section titled “Drag to Add with Shape”

You can also add a node by dragging the connection handle to an empty area of the canvas. A shape picker appears at the drop location, letting you choose the shape before the node is inserted. A new edge connecting the source node to the new node is added automatically.

Connecting Elements

Section titled “Connecting Elements”

Drag to Connect

Section titled “Drag to Connect”

Hover over a node in edit mode to reveal a connection handle. Drag from the handle to a target node to create a new edge between them. The corresponding edge syntax is added to the diagram source automatically.

Edge Retargeting

Section titled “Edge Retargeting”

Drag an existing edge’s endpoint to a different node to change where the connection points. The source code is updated to reflect the new target.

A selected edge with link style properties in the Style Pane

Moving Elements

Section titled “Moving Elements”

Click and drag a selected node to reposition it. The source code is updated to reflect the new position.

Moving Nodes Between Subgraphs

Section titled “Moving Nodes Between Subgraphs”

Drag a node into or out of a subgraph to change its scope. When a node crosses a subgraph boundary, the source code structure is updated accordingly.

Moving Subgraphs

Section titled “Moving Subgraphs”

To move a subgraph, click it to select it first, then drag. You can drag a subgraph into another subgraph to nest it.

With multiple elements selected, dragging moves all selected elements together as a batch.

Grouping

Section titled “Grouping”

Select one or more nodes and press Command + G Control + G to wrap them in a new subgraph. Grouping works with a single node, multiple nodes, or a mixed selection of nodes and subgraphs.

When a selected subgraph already contains other selected elements, the nested elements are kept inside their parent automatically.

Inline Editing

Section titled “Inline Editing”

Double-click a node label, subgraph title, or edge label to edit its text inline in the preview. An editable text overlay appears over the element. Changes are written back to the source code on commit (press Enter Enter or click outside the element).

Typography Shortcuts

Section titled “Typography Shortcuts”

Press Command + B Control + B to toggle bold or Command + I Control + I to toggle italic on the selected element’s label. These shortcuts work on any element that supports typography (nodes, subgraph titles, and edge labels).

When multiple elements are selected, the shortcut applies to all of them at once.

Deleting Elements

Section titled “Deleting Elements”

Press the Backspace Backspace or Delete Delete key to remove the currently selected element or elements. The corresponding source code is removed from the diagram.

Batch deletion works the same way: select multiple elements, then press Delete to remove them all.

Undo

Section titled “Undo”

All edit mode operations integrate with the IDE’s undo system. Press Command + Z Control + Z to revert any change made through the preview.

See Also

Section titled “See Also”