Routing

Edge routing determines how connections between nodes are drawn in your diagram. NgDiagram provides flexible routing where each routing algorithm:

Calculates the points that define the edge path
Draws the SVG path from those points
Computes positions along the path for labels and decorations

Routing algorithms automatically calculate optimal paths, with an option to provide predefined waypoints for static edge paths.

Built-in Algorithms

NgDiagram includes three routing algorithms:

Polyline

The simplest routing that connects points with straight line segments. In auto mode, it creates a direct line between source and target. In manual mode, it can create multi-segment paths by connecting user-provided waypoints with straight lines.

Orthogonal

Creates paths using only horizontal and vertical segments, ideal for technical diagrams and flowcharts. Supports configurable segment lengths and optional rounded corners.

Bezier

Produces smooth curved connections using cubic Bézier curves.

Using Routing

To specify a routing algorithm for an edge, set the routing property in the edge data:

1
  model = initializeModel({
26 collapsed lines
2
    nodes: [
3
      {
4
        id: 'source-node',
5
        position: { x: 150, y: 240 },
6
        data: { label: 'Source' },
7
        rotatable: true,
8
      },
9
      {
10
        id: '2',
11
        position: { x: 600, y: 30 },
12
        data: { label: 'Target 1' },
13
        rotatable: true,
14
      },
15
      {
16
        id: '3',
17
        position: { x: 600, y: 180 },
18
        data: { label: 'Target 2' },
19
        rotatable: true,
20
      },
21
      {
22
        id: '4',
23
        position: { x: 600, y: 330 },
24
        data: { label: 'Target 3' },
25
        rotatable: true,
26
      },
27
    ],
28
    edges: [
29
      {
30
        id: '1',
31
        source: 'source-node',
32
        sourcePort: 'port-right',
33
        targetPort: 'port-left',
34
        target: '2',
35
        data: {},
36
        routing: 'polyline',
37
        type: 'routing-edge',
38
      },
39
      {
40
        id: '2',
41
        source: 'source-node',
42
        sourcePort: 'port-right',
43
        targetPort: 'port-left',
44
        target: '3',
45
        data: {},
46
        routing: 'orthogonal',
47
        type: 'routing-edge',
48
      },
49
      {
50
        id: '3',
51
        source: 'source-node',
52
        sourcePort: 'port-right',
53
        targetPort: 'port-left',
54
        target: '4',
55
        data: {},
56
        routing: 'bezier',
57
        type: 'routing-edge',
58
      },
59
    ],
60
  });
61
}

When no routing is specified, the default routing algorithm (orthogonal) is used. The default can be changed through configuration.

For custom edge components, you can provide routing directly in the template using NgDiagramBaseEdgeComponent:

1
<ng-diagram-base-edge
2
  [edge]="edge"
3
  [routing]="'orthogonal'"
4
  stroke="var(--ngd-default-edge-stroke)"
5
/>

Routing Modes

Each edge can operate in one of two routingMode options:

Auto Mode (Default)

In auto mode, the routing algorithm automatically calculates the path between nodes. The list of points is calculated by the routing algorithm and should be treated as read-only. The path updates automatically when nodes move or resize.

1
const edge = {
2
  id: 'edge1',
3
  source: 'node1',
4
  target: 'node2',
5
  routing: 'orthogonal',
6
  routingMode: 'auto', // or omit for default
7
  data: {},
8
};

Manual Mode

Manual mode gives you full control over the edge path by allowing you to provide your own list of points. The routing algorithm is still used to draw the SVG path from these points and calculate label positions. When nodes move, you control what happens - the path can remain unchanged, or you can programmatically update the points as needed.

Try moving the nodes in the example below - notice how the edge path remains fixed:

1
  model = initializeModel({
14 collapsed lines
2
    nodes: [
3
      {
4
        id: 'node1',
5
        position: { x: 100, y: 150 },
6
        data: { label: 'Move me!' },
7
        rotatable: true,
8
      },
9
      {
10
        id: 'node2',
11
        position: { x: 500, y: 150 },
12
        data: { label: 'Move me too!' },
13
        rotatable: true,
14
      },
15
    ],
16
    edges: [
17
      {
18
        id: 'manual-edge',
19
        source: 'node1',
20
        sourcePort: 'port-right',
21
        target: 'node2',
22
        targetPort: 'port-left',
23
        routing: 'orthogonal',
24
        routingMode: 'manual',
25
        points: [
26
          { x: 285, y: 172 },
27
          { x: 345, y: 172 },
28
          { x: 345, y: 100 },
29
          { x: 445, y: 100 },
30
          { x: 445, y: 172 },
31
          { x: 500, y: 172 },
32
        ],
33
        data: {},
34
      },
35
    ],
36
  });
37
}

This is useful for creating custom edge behaviors, fixed connection paths, or implementing your own edge update logic.

Configuration

You can configure routing behavior globally through the diagram’s configuration:

1
@Component({
16 collapsed lines
2
  imports: [NgDiagramComponent, NgDiagramBackgroundComponent],
3
  providers: [provideNgDiagram()],
4
  template: `
5
    <div class="not-content diagram">
6
      <ng-diagram [model]="model" [config]="config">
7
        <ng-diagram-background />
8
      </ng-diagram>
9
    </div>
10
  `,
11
  styles: `
12
    .diagram {
13
      display: flex;
14
      height: var(--ng-diagram-height);
15
      border: var(--ng-diagram-border);
16
    }
17
  `,
18
})
19
export class DiagramComponent {
20
  config: NgDiagramConfig = {
21
    zoom: {
22
      zoomToFit: {
23
        onInit: true,
24
      },
25
    },
26
    edgeRouting: {
27
      defaultRouting: 'orthogonal', // Set default routing
28
      orthogonal: {
29
        firstLastSegmentLength: 30, // Length of first and last segments
30
        maxCornerRadius: 8, // Maximum radius for rounded corners
31
      },
32
      bezier: {
33
        bezierControlOffset: 150, // Distance of control points from nodes
34
      },
35
    },
36
  };
43 collapsed lines
37

38
  model = initializeModel({
39
    metadata: {
40
      viewport: { x: 0, y: 0, scale: 0.8 },
41
    },
42
    nodes: [
43
      {
44
        id: 'node1',
45
        position: { x: 100, y: 100 },
46
        data: { label: 'Source' },
47
      },
48
      {
49
        id: 'node2',
50
        position: { x: 400, y: 100 },
51
        data: { label: 'Target 1' },
52
      },
53
      {
54
        id: 'node3',
55
        position: { x: 400, y: 250 },
56
        data: { label: 'Target 2' },
57
      },
58
    ],
59
    edges: [
60
      {
61
        id: 'edge1',
62
        source: 'node1',
63
        sourcePort: 'port-right',
64
        target: 'node2',
65
        targetPort: 'port-left',
66
        // No routing specified - uses default 'orthogonal' from config
67
        data: {},
68
      },
69
      {
70
        id: 'edge2',
71
        source: 'node1',
72
        sourcePort: 'port-rigth',
73
        target: 'node3',
74
        targetPort: 'port-left',
75
        routing: 'bezier', // Explicitly set to bezier
76
        data: {},
77
      },
78
    ],
79
  });
80
}

Custom Routing Algorithms

NgDiagram’s routing system is extensible. You can create custom routing algorithms by implementing the EdgeRouting interface, or by creating custom edge components that generate their own paths using manual mode.

Manual Mode Approach

You can create dynamic custom paths by computing points in your edge component and using manual routing mode. Here’s an example of a sinusoid edge that updates its path dynamically as nodes move:

1
import { Component, computed, input } from '@angular/core';
2
import {
3
  NgDiagramBaseEdgeComponent,
4
  type Edge,
5
  type NgDiagramEdgeTemplate,
6
  type Point,
7
} from 'ng-diagram';
8

9
@Component({
10
  template: `<ng-diagram-base-edge
11
    [edge]="customEdge()"
12
    stroke="var(--ngd-default-edge-stroke)"
13
    [targetArrowhead]="'ng-diagram-arrow'"
14
  ></ng-diagram-base-edge>`,
15
  styleUrl: './sinusoid-edge.component.scss',
16
  imports: [NgDiagramBaseEdgeComponent],
17
})
18
export class SinusoidEdgeComponent implements NgDiagramEdgeTemplate {
19
  edge = input.required<Edge>();
20

21
  customEdge = computed(() => {
22
    const edge = this.edge();
23
    const { sourcePosition, targetPosition } = edge;
24

25
    if (!sourcePosition || !targetPosition) {
26
      return edge;
27
    }
28

29
    const points = this.generateSinusoidPoints(sourcePosition, targetPosition);
30

31
    return {
32
      ...edge,
33
      points,
34
      routing: 'polyline',
35
      routingMode: 'manual' as const,
36
    };
37
  });
46 collapsed lines
38

39
  private generateSinusoidPoints(sourcePosition: Point, targetPosition: Point) {
40
    const startX = sourcePosition.x;
41
    const startY = sourcePosition.y;
42
    const endX = targetPosition.x;
43
    const endY = targetPosition.y;
44

45
    // Calculate distance and angle between points
46
    const distance = Math.sqrt(
47
      Math.pow(endX - startX, 2) + Math.pow(endY - startY, 2)
48
    );
49
    const angle = Math.atan2(endY - startY, endX - startX);
50

51
    // Sinusoidal wave parameters
52
    const amplitude = 20;
53
    const frequency = Math.max(2, distance / 100);
54
    const segments = Math.max(20, Math.floor(distance / 5));
55

56
    const points = [{ x: startX, y: startY }];
57

58
    // Generate sinusoidal curve points
59
    for (let i = 1; i < segments; i++) {
60
      const t = i / segments;
61

62
      // Base position along the straight line
63
      const baseX = startX + (endX - startX) * t;
64
      const baseY = startY + (endY - startY) * t;
65

66
      // Calculate perpendicular offset using sine wave
67
      // Fade out amplitude as we approach the end to ensure smooth connection
68
      const fadeFactor = i < segments - 5 ? 1 : (segments - i) / 5;
69
      const sineOffset =
70
        Math.sin(t * 2 * Math.PI * frequency) * amplitude * fadeFactor;
71
      const perpAngle = angle + Math.PI / 2;
72

73
      const x = baseX + Math.cos(perpAngle) * sineOffset;
74
      const y = baseY + Math.sin(perpAngle) * sineOffset;
75

76
      points.push({ x, y });
77
    }
78

79
    // Always end exactly at the target position
80
    points.push({ x: endX, y: endY });
81

82
    return points;
83
  }
84
}

This approach is ideal when you want the path to update automatically based on node positions and when you just need to compute points - the SVG path can be computed by a built-in routing algorithm (in this case, polyline was sufficient).

Registering New Routing in the Library

For more control and reusability across different edge types, you can create a custom routing algorithm by implementing the EdgeRouting interface and registering it via NgDiagramService.registerRouting(). Once registered, the routing becomes available globally across all edges in your diagram.

Here’s a complete example of an arc routing that uses SVG elliptical arcs to create curved connections:

arc-routing.ts
diagram.component.ts

1
import type { EdgeRouting, EdgeRoutingContext, Point } from 'ng-diagram';
2

3
/**
4
 * Arc routing implementation using SVG elliptical arcs.
5
 *
6
 * Creates curved connections using SVG arc commands
7
 */
8
export class ArcRouting implements EdgeRouting {
9
  name = 'arc';
10

11
  /**
12
   * Computes the points for an arc path.
13
   * For arcs, we only need the source and target points.
14
   */
15
  computePoints(context: EdgeRoutingContext): Point[] {
16
    const { sourcePoint, targetPoint } = context;
17
    return [
18
      { x: sourcePoint.x, y: sourcePoint.y },
19
      { x: targetPoint.x, y: targetPoint.y },
20
    ];
21
  }
22

23
  /**
24
   * Generates an SVG path string using an elliptical arc.
25
   *
26
   * The arc command (A) creates a curved path between source and target.
27
   * Format: A rx ry x-axis-rotation large-arc-flag sweep-flag x y
28
   */
29
  computeSvgPath(points: Point[]): string {
30
    if (points.length < 2) return '';
31

32
    const start = points[0];
33
    const end = points[points.length - 1];
34

35
    // Calculate distance to use as radius
36
    const dx = end.x - start.x;
37
    const dy = end.y - start.y;
38
    const distance = Math.sqrt(dx * dx + dy * dy);
39

40
    const radiusMultiplier = 0.5;
41
    const radius = distance * radiusMultiplier;
42

43
    // Create arc: sweep-flag=1 creates a clockwise arc (curves downward/rightward)
44
    return `M ${start.x},${start.y} A ${radius} ${radius} 0 0 1 ${end.x},${end.y}`;
45
  }
46
}

1
import '@angular/compiler';
2

3
import { Component, inject } from '@angular/core';
4
import {
5
  initializeModel,
6
  NgDiagramBackgroundComponent,
7
  NgDiagramComponent,
8
  NgDiagramService,
9
  provideNgDiagram,
10
  type DiagramInitEvent,
11
  type NgDiagramConfig,
12
} from 'ng-diagram';
13
import { ArcRouting } from './arc-routing';
14

15
@Component({
16
  selector: 'custom-routing',
17
  imports: [NgDiagramComponent, NgDiagramBackgroundComponent],
18
  providers: [provideNgDiagram()],
19
  template: `
20
    <div class="not-content diagram">
21
      <ng-diagram
22
        [model]="model"
23
        [config]="config"
24
        (diagramInit)="onDiagramInit($event)"
25
      />
26
        <ng-diagram-background />
27
      </ng-diagram>
28
    </div>
29
  `,
30
  styles: `
31
    .diagram {
32
      display: flex;
33
      height: var(--ng-diagram-height);
34
      border: var(--ng-diagram-border);
35
    }
36
  `,
37
})
38
export class DiagramComponent {
39
  private diagramService = inject(NgDiagramService);
40

41
  config = {
42
    zoom: {
43
      zoomToFit: {
44
        onInit: true,
45
      },
46
    },
47
    edgeRouting: {
48
      arc: {
49
        radiusMultiplier: 0.5,
50
      },
51
    },
52
  } satisfies NgDiagramConfig;
53

54
  onDiagramInit(_: DiagramInitEvent) {
55
    this.diagramService.registerRouting(new ArcRouting());
56
  }
57

58
  model = initializeModel({
59
    nodes: [
60
      {
61
        id: 'node1',
62
        position: { x: 100, y: 50 },
63
        data: { label: 'Node 1' },
64
      },
65
      {
66
        id: 'node2',
67
        position: { x: 400, y: 50 },
68
        data: { label: 'Node 2' },
69
      },
70
    ],
71
    edges: [
72
      {
73
        id: 'edge1',
74
        source: 'node1',
75
        target: 'node2',
76
        sourcePort: 'port-right',
77
        targetPort: 'port-left',
78
        data: {},
79
        routing: 'arc',
80
      },
81
    ],
82
  });
83
}

This approach gives you full control over path generation, configuration options, and point calculations. The three required methods work together: computePoints defines the geometric points, computeSvgPath renders them as SVG, and computePointOnPath positions labels and decorations along the path.

Edges Overview → | Custom Edges → | Edge Labels →