Custom SVG Connection Ports & Multi-Layer Cross-Layer Positioning in JointJS

[Nitin-Shandilya]

Introduction

We are building a Plant Automation HMI application using JointJS that includes a pipeline designer with a large library of custom SVG-based industrial elements (pumps, tanks, motors, valves, etc.). We have two architectural questions regarding JointJS capabilities that are central to our implementation.

Steps to reproduce

I have a couple of technical questions regarding JointJS implementation for a Plant Automation HMI project we are currently developing.

1. SVG Equipment Connection Points
   We are aiming to build a pipeline designer similar to the SCADA HMI demo on the JointJS website. Our application includes a large library of custom SVG-based industrial elements — pumps, tanks, motors, and other assets. Rather than generic line-with-arrow connections, we need pipe connections to originate and terminate at precise inlet/outlet positions on each SVG element, so the layout appears realistic and physically accurate.
   Could you advise on the recommended approach for defining and managing named connection ports on custom SVG shapes in JointJS?

2. Multi-Layer Design with Cross-Layer Positional Awareness
   We also need to support multiple independent layers — for example, a Physical Layer, an Electronics Layer, and a Map Layer. A key requirement is that when a user switches from the Physical Layer to the Electronics Layer, the elements from the Physical Layer should remain spatially visible or referenced, so that wiring connections in the Electronics Layer can be accurately aligned to the physical equipment positions.
   What is the recommended approach in JointJS for implementing this kind of layer system with cross-layer positional context?

Any guidance, examples, or best practices on either of these points would be greatly appreciated.

Restrictions & Constraints

No response

Does your question relate to JointJS or JointJS+. Select both if applicable.

JointJS+

[ZoranJambor]

Great questions, Nitin-Shandilya! 🙏

1. Connection points on custom SVG equipment

Use the Ports API rather than raw magnets. You get named, addressable points, and links snap to them automatically. For precise inlet/outlet positions on irregular SVG shapes, define a port group with the absolute layout and give each port explicit coordinates (px, % of the element bbox, or calc() expressions):

const Pump = dia.Element.define('hmi.Pump', {
    size: { width: 80, height: 60 },
    ports: {
        groups: {
            pipe: {
                position: { name: 'absolute' },
                attrs: { portBody: { r: 5, magnet: 'active' } },
                markup: util.svg`<circle @selector="portBody"/>`
            }
        },
        items: [
            { id: 'inlet',  group: 'pipe', args: { x: 0,         y: '50%' } },
            { id: 'outlet', group: 'pipe', args: { x: 'calc(w)', y: '50%' } }
        ]
    }
}, {
    markup: util.svg`<path @selector="body"/>` // your custom SVG here
});

Connect a pipe to a specific port by id:

link.source({ id: pump.id, port: 'outlet' });
link.target({ id: tank.id, port: 'inlet' });

Because ports are positioned relative to the element bbox, they stay attached when the element is moved or resized. You can also have multiple groups on one element (e.g. a pipe group for process connections and a separate signal group for instrumentation terminals).

To read a port's resolved coordinates at any time — useful for the alignment in (2) — use element.getPortsPositions(groupName), which returns positions keyed by port id, relative to the element origin:

const positions = pump.getPortsPositions('pipe'); // { inlet: {x, y, angle}, outlet: {...} }
const origin = pump.position();
const inletAbs = { x: origin.x + positions.inlet.x, y: origin.y + positions.inlet.y };

Reference: Port layouts.

2. Multi-layer with cross-layer positional awareness

JointJS 4.2 introduced a first-class Layers API, and the positional awareness you're after is essentially free: all layers share the same Paper coordinate system. A wire on the Electronics layer at (x, y) is in the exact same coordinate space as a pump on the Physical layer — there's nothing to synchronize.

graph.addLayer({ id: 'map' });        // rendered back -> front in this order
graph.addLayer({ id: 'physical' });
graph.addLayer({ id: 'electronics' });

graph.setDefaultLayer('physical');
graph.addCells([pump, tank]);         // -> physical layer

graph.setDefaultLayer('electronics');
graph.addCells([wire1, wire2]);       // -> electronics layer

Each layer is its own model with its own cell collection and z-index stacking context, and the whole thing serializes through graph.toJSON() / fromJSON() (layers + default layer are included).

Because the coordinate space is shared, a link on the Electronics layer can target a port on a Physical-layer element directly by id, and it will render and re-route correctly, even when you drag the physical equipment:

wire.source({ id: plc.id,  port: 'o1' });    // element on 'electronics'
wire.target({ id: pump.id, port: 'signal' }); // element on 'physical'

To keep physical equipment visible as a reference while editing the Electronics layer, don't hide the Physical layer. Keep it rendered but non-interactive and dimmed, so it acts as a "ghost underlay." One straightforward way is to set opacity / pointer-events on the layer's view node:

const layerView = paper.getLayerView('physical');
layerView.el.style.opacity = 0.2;
layerView.el.style.pointerEvents = 'none';

If you need "what physical asset is under this wiring point, and which layer is it on," graph.findElementsAtPoint(point) and graph.getCellLayerId(cell) cover that.

References: Graph API (layer methods) · GraphLayer · 4.2 release overview.

Requires JointJS 4.2+. On an older version, you can get the same effect with a single graph plus a layer attribute per cell and opacity toggling (it works because everything already shares one coordinate system), but the 4.2 Layers API is much cleaner and worth the upgrade.

Let me know if this helps. 🙂