Relinking

since v1.4.0

The edge relinking feature lets users reconnect existing edges by dragging their endpoints. A selected edge shows a handle at each end that can be relinked. Dragging a handle previews the new connection live and commits it on drop.

Select an edge to see its handles: the first edge can be relinked at both ends, the second only at its target end, and the third is locked. Drag a handle to another port to reconnect the edge, or drop it on empty canvas to detach that end.

Enabling Relinking

Relinking is off by default. linking.defaultRelinkable sets the default for every edge: true lets users drag both ends, while 'source' or 'target' lets them drag only that end.

1
  config = {
6 collapsed lines
2
    zoom: {
3
      zoomToFit: {
4
        onInit: true,
5
        padding: 80,
6
      },
7
    },
8
    linking: {
9
      // Both ends of every edge can be relinked, unless the edge sets its own `relinkable`
10
      defaultRelinkable: true,
11
    },
12
    // A handle dropped on empty canvas detaches that end instead of reverting the relink
13
    danglingEdges: {
14
      enabled: true,
15
    },
16
  } satisfies NgDiagramConfig;

With defaultRelinkable: true, every selected edge rendered by ng-diagram-base-edge shows a handle at each end. The preview of a new edge that is being drawn never shows handles.

Controlling Which Edges Can Be Relinked

An edge can override the default with its own relinkable property. The effective value is the edge’s relinkable when it is set, otherwise linking.defaultRelinkable. This value decides which ends the user can drag:

Effective value	Source end	Target end
`true`	yes	yes
`'source'`	yes	no
`'target'`	no	yes
`false`	no	no

Edges in the initial model, edges added with addEdges, and pasted edges take relinkable from their own data:

1
  model = initializeModel({
8 collapsed lines
2
    nodes: [
3
      { id: 'a', position: { x: 100, y: 60 }, data: { label: 'A' } },
4
      { id: 'b', position: { x: 550, y: 60 }, data: { label: 'B' } },
5
      { id: 'c', position: { x: 100, y: 190 }, data: { label: 'C' } },
6
      { id: 'd', position: { x: 550, y: 190 }, data: { label: 'D' } },
7
      { id: 'e', position: { x: 100, y: 320 }, data: { label: 'E' } },
8
      { id: 'f', position: { x: 550, y: 320 }, data: { label: 'F' } },
9
    ],
10
    edges: [
11
      {
12
        id: 'both-ends',
13
        source: 'a',
14
        sourcePort: 'port-right',
15
        target: 'b',
16
        targetPort: 'port-left',
17
        // No `relinkable`: the config default applies
18
        data: { label: 'both ends' },
19
      },
20
      {
21
        id: 'target-only',
22
        source: 'c',
23
        sourcePort: 'port-right',
24
        target: 'd',
25
        targetPort: 'port-left',
26
        relinkable: 'target',
27
        data: { label: 'target end only' },
28
      },
29
      {
30
        id: 'locked',
31
        source: 'e',
32
        sourcePort: 'port-right',
33
        target: 'f',
34
        targetPort: 'port-left',
35
        relinkable: false,
36
        data: { label: 'locked' },
37
      },
38
    ],
39
  });

Edges drawn by the user get the value from finalEdgeDataBuilder, the same callback where an app assigns their type. To make only one edge type relinkable, keep the default at false and set relinkable: true for that type:

1
const config: NgDiagramConfig = {
2
  linking: {
3
    // defaultRelinkable stays false: only edges with relinkable: true can be relinked
4
    finalEdgeDataBuilder: (edge) => ({ ...edge, type: 'draft', relinkable: true }),
5
  },
6
};

For the opposite case, where every edge is relinkable except a few locked ones, set defaultRelinkable: true and put relinkable: false on the locked edges.

The builder runs only for edges that the user draws. Loaded edges use the default or their own relinkable property.

How It Works

Press a handle and drag it. The endpoint follows the pointer as a live preview and snaps to nearby ports, the same as when drawing an edge.
A click on a handle without dragging (less than about 5 px of pointer movement) does nothing: no relink starts and no events fire.
Pressing Escape (or calling cancelActiveInteraction()) cancels the relink, and the edge stays unchanged.

Drop Outcomes

What happens on release depends on where the endpoint is dropped:

On a valid port — the edge is reconnected to that node and port.
On empty canvas — the endpoint becomes a free (dangling) endpoint anchored at the drop position. This requires danglingEdges.enabled to be true and shouldKeepOnDrop to keep the edge. A canvas drop is not a connection, so validateConnection is not called for it. With dangling edges disabled, or when shouldKeepOnDrop returns false, the relink is reverted with reason noTarget.
On an invalid target — for example a hidden node, a missing port, a port with the wrong direction, or a connection that the validator refuses — the relink is reverted with reason invalidConnection.
Back on the original port — nothing changes: the model stays as it is, and the gesture reports success: false with reason cancelled.

A reverted relink never changes the model. The edge stays as it was.

Validating Reconnections

Connections made by relinking go through the same linking.validateConnection callback as edge drawing. The optional fifth argument, a ConnectionValidationContext, tells you which operation is being validated. For relinks it carries reason: 'relink', the edge being relinked, and the end that is being dragged:

1
const config: NgDiagramConfig = {
2
  linking: {
3
    validateConnection: (source, sourcePort, target, targetPort, context) => {
4
      if (source?.id === target?.id) {
5
        return false; // no self-connections
6
      }
7
      if (context?.reason === 'relink') {
8
        // A relinked end stays inside the edge's current group
9
        return source?.groupId === target?.groupId;
10
      }
11
      return true;
12
    },
13
  },
14
};

Use context.reason === 'relink' for rules about the drop target, like the same-group rule above. To lock an edge or one of its ends, use relinkable instead. The validator runs only on drop, so an edge locked through the validator would still show handles and let the user drag them.

Note that source or target can be null. This happens when the other end of the relinked edge is free, for example when the user relinks the target end of an edge whose source end is dangling. source is also null for draws started with startLinkingFromPosition. Guard against null in your validator.

Events

Two events report the gesture:

edgeRelinkStarted — fires when the user starts dragging an endpoint. The payload carries the edge (a snapshot taken at gesture start) and the end that is being dragged.
edgeRelinkEnded — fires when the gesture ends, whatever the outcome. The payload carries:
- edge — the edge after the relink, or the unchanged snapshot on failure
- end — the dragged endpoint
- previousNode and previousPort when the endpoint was connected before, or previousPosition when it was free
- dropPosition and success
- on a reconnect, target and targetPort name the new connection; on failure, reason is one of noTarget | invalidConnection | cancelled

1
<ng-diagram (edgeRelinkStarted)="onRelinkStarted($event)" (edgeRelinkEnded)="onRelinkEnded($event)" />

1
onRelinkEnded(event: EdgeRelinkEndedEvent) {
2
  if (event.success && event.target) {
3
    console.log(`Reconnected ${event.end} of ${event.edge.id} from ${event.previousNode?.id} to ${event.target.id}`);
4
  } else if (event.success) {
5
    console.log(`Detached ${event.end} of ${event.edge.id} at`, event.dropPosition);
6
  } else {
7
    console.log('Relink reverted:', event.reason);
8
  }
9
}

Customization

Relink Handles

A handle is a ring at each end of the edge. A handle shows a halo on hover and is filled while its end is dragged. The handles stay visible during the drag.

Here are the CSS variables you can use to style the relink handles globally:

1
  --ngd-relink-handle-size               // Outer diameter of the handle (the stroke is inside)
2
  --ngd-relink-handle-stroke-width       // Stroke width of the handle
3
  --ngd-relink-handle-fill               // Fill color of the handle
4
  --ngd-relink-handle-fill-hover         // Fill color on hover
5
  --ngd-relink-handle-fill-drag          // Fill color while the end is dragged
6
  --ngd-relink-handle-stroke             // Stroke (outline) color of the handle
7
  --ngd-relink-handle-stroke-hover       // Stroke color on hover
8
  --ngd-relink-handle-stroke-drag        // Stroke color while the end is dragged
9
  --ngd-relink-handle-halo-size          // Width of the halo around the handle
10
  --ngd-relink-handle-halo-color-hover   // Halo color on hover
11
  --ngd-relink-handle-halo-color-drag    // Halo color while the end is dragged

You can also override them per edge with the matching --edge-relink-handle-* variables, in the same way as --edge-stroke. Each state has its own variable, so set the hover and drag colors together with the default ones:

1
ng-diagram-base-edge.my-edge {
2
  --edge-relink-handle-size: 0.875rem;
3
  --edge-relink-handle-fill: #fff;
4
  --edge-relink-handle-fill-hover: #fff;
5
  --edge-relink-handle-fill-drag: #3b82f6;
6
  --edge-relink-handle-stroke: #3b82f6;
7
  --edge-relink-handle-stroke-hover: #3b82f6;
8
  --edge-relink-handle-stroke-drag: #3b82f6;
9
  --edge-relink-handle-halo-color-hover: rgba(59, 130, 246, 0.4);
10
  --edge-relink-handle-halo-color-drag: rgba(59, 130, 246, 0.4);
11
}

Each handle has a larger invisible hit area around it. It is 24 screen pixels wide. Its size is adjusted for zoom, so the handles stay easy to grab at any zoom level without growing visually. Hovering over the hit area shows the halo, the same as hovering over the handle itself.

Dangling Edges → | Edges Overview → | Edge Selection →