Self-edges/loops look very awkward in state diagrams

[hjfreyer]

Description

In state diagrams where a state connects to itself, it looks, well... ugly. Like the edge was about to point to a different node, but then realized it was heading in the wrong direction and doubled-back on itself.

Steps to reproduce

stateDiagram-v2
    [*] --> Node
    Node --> Node: Self Edge

Or, in the live editor.

Screenshots

Code Sample

Setup

• Mermaid version: v11.4.1
• Browser and Version: Chrome Version 132.0.6834.208 (Official Build) (64-bit)

Suggested Solutions

Compare that to this graphviz digraph:

digraph G {
  start -> n;

  n [label= "Node"];
  n -> n [label = "Self Edge"];
}

So much more natural. The salient differences are the fact that the edge is to the side of the node, and that it doesn't have the unfortunate kink in it.

Additional Context

Issue #1443 may be related. It's complaining about rendering of self-edges, but it's less clear to me what the specific complaint is.

[sfarina]

I came here to post about this issue as well. It gets wild if you're trying to illustrate a finite state machine:

stateDiagram-v2
  A --> B
  B-->B
  B -->A
  A --> C
  C --> C
  C --> B
  C --> A

[BambioGaming]

Hello,

I completely agree that self-loops in Mermaid state diagrams currently do not render as cleanly as they do in Graphviz digraphs. The issue appears to stem from how self-loops are treated like standard edges rather than being explicitly optimized for circular positioning.

Possible Issues in the Current Implementation

1. Lack of Explicit Self-Loop Handling

• The stateDb.js processing functions that do not differentiate self-loops from regular transitions.
• As a result, the self-loop is drawn as a reversed transition rather than a properly curved arc.

2. Edge Routing & Layout Constraints

• The automatic layout engine does not prioritize self-loops, causing them to be positioned awkwardly.
• Graphviz, by contrast, uses explicit loop placement rules that result in smoother loops.

3. Styling & Customization Limitations

• The setStyle() function in stateDb.js does not provide options for defining self-loop curvature or positioning.
• Unlike Graphviz, Mermaid does not support loop-specific attributes like headport or tailport to adjust where the loop attaches to the node.

Possible Fixes & Enhancements

• Introduce explicit self-loop detection, ensuring that self-loops are styled separately from regular edges.
• Add support for loop curvature controls in setStyle(), similar to how Graphviz allows adjustments.
• Implement edge anchor customization (e.g., allowing users to specify where the self-loop attaches to the node).

Would love to hear your thoughts.

[nour0205]

Hello @hjfreyer

I have also tested self-loops across multiple diagram types and confirm that the issue affects state diagrams class diagrams and flowcharts, where loops are misaligned, overlapping, or bending unnaturally even when forcing a horizontal layout.

However, like you mentioned for graphviz, sequence diagrams also render self-loops correctly, which requires further investigation.

Screenshots for Reference:

• Correct self-loops in sequence diagrams
• Misaligned self-loops in state diagrams and flowcharts