Skip to main content
  1. Index

Links

Use the Link class to implement a visual relationship between nodes. See samples that make use of customized Links in the samples index.

Links are normally created in the following ways:

LinkingTool.insertLink is ideal when adding links while having minimal information about the model. An example of it can be found in the Organizational Chart Editor sample.

The simplest links are those without arrowheads to indicate a visual direction. Either the relationship really is non-directional, or the direction is implied by the organization of the diagram.

The template contains a Shape, which is the main element and the line that is drawn between nodes. After the link's route is computed, the main Shape will get a Geometry based on the points in the route.

By default, the way that the model and diagram know about the node data references of a link data is by looking at its from and to properties. If you want to use different properties on the link data, set GraphLinksModel.linkFromKeyProperty to be the name of the property that results in the node data's key, and similarly for the GraphLinksModel.linkToKeyProperty.

Arrowheads

Often links need to indicate directionality by using arrowheads. GoJS makes it easy to create common arrowheads: just add a Shape and set its Shape.toArrow property. Setting that property will automatically assign a Geometry to the Shape.geometry and will set other properties so that the arrowhead is positioned at the head of the link and is pointing in the correct direction. Of course you can set the other Shape properties such as Shape.fill in order to customize the appearance of the arrowhead.

You can see all of the predefined arrowhead types in the Arrowheads Sample. For more information on gradients, see Brushes.

You can also have an arrowhead at the start of the link: set the Shape.fromArrow property. Note that an arrowhead normally goes along the path of the link regardless of its position on the path, so just as with a real arrow, setting { fromArrow: "TripleFeathers" } has the "feathers" pointing forward. If the link is meant to be bi-directional, the arrowhead name for the "from" end of a link should start with the string "Backward...".

Routing

If you want to customize the path that each Link takes, you need to set properties on the link. The property that has the most general effect on the points that the link's route follows is Link.routing.

This example shows the two most common routing values: Routing.Normal (the default) and Routing.Orthogonal.

Note that the computed route also depends on the properties of the node, including its shape. There are other properties, including GraphObject.fromSpot and GraphObject.toSpot, that affect the route. For more discussion about spots, please read this learn page: Link connection points. Furthermore, some Layouts set properties on links to control their routing according to what the layout expects.

You can also set Link.routing to Routing.AvoidsNodes:

If you move the nodes interactively, you can see how the link's route adjusts to avoid crossing over nodes. Notice that a small gap between nodes might not be considered wide enough for links to go through.

If a node is very close to or overlaps with either the link's Link.fromNode or Link.toNode and would block the link's route, it ignores that node, treating it as if it were just an extension of the connected node. Also, if no node-avoiding route exists because there is a ring of nodes around one of the connected nodes, the routing algorithm will give up and cross over some nodes anyway.

You can declare that it is OK to route through a node by setting Node.avoidable to false. This is commonly done for Groups to allow links connecting outside of the group to route nicely within the group.

Note that the use of AvoidsNodes routing is distinctly slower than normal Orthogonal routing, especially for large diagrams.

For more complex and customizable routing behaviors, you can use the Router class. Routers operate on the collection of links in a Diagram or Group after the Layout has been completed. See the learn page on Routers for more information.

End segment lengths

One might want to change the length of the link segment attached to the node. As in, require the node to go straight for a certain distance before letting it route normally. The properties that control this are GraphObject.fromEndSegmentLength and GraphObject.toEndSegmentLength. While this can be useful for nearly all routing/curve combinations, a common usage is in orthognal routing.

Using Link.fromSpot and Link.toSpot, these links have been forced to take a roundabout route. In the top pair of nodes, you can see the default behavior of the routing in this case. In the bottom pair, you can see a shortened fromEndSegmentLength and a lengthened toEndSegmentLength

Curves

Once the Link.routing determines the route (i.e., the sequence of points) that the link will take, other properties control the details of how the link shape gets its path geometry. The first such property is Link.curve, which controls whether the link shape has basically straight segments or is a big curve.

The default value for Link.curve is Curve.None, which produces link shapes with straight segments as you see above.

A value of Curve.Bezier produces a naturally curved path for the link shape.

If there are multiple links, GoJS will automatically compute reasonable values for the curviness of each link, unless you assign Link.curviness explicitly.

You can control how curved it is by setting the Link.curviness property. The default produces a slight curve.

Another kind of curviness comes from rounded corners when the Link.routing is Orthogonal or AvoidsNodes.

Another kind of curviness (or lack thereof) comes from setting Link.curve to Curve.JumpOver or Curve.JumpGap. JumpOver causes little "hops" in the path of an orthogonal link that crosses another orthogonal link that also has a JumpOver/JumpGap curve. JumpGap causes little "gaps" in the path instead.

This example uses a custom font for icons. See more about fonts in the TextBlocks page.

Note that the use of link jumping is distinctly slower than normal links because all of the crossing points must be computed and the geometry of the link shape will be more complex.

It can be difficult to click on links that have a thin Link.path. One could set the Shape.strokeWidth to a larger value, such as 8, but you may not want that appearance. One common solution is to add a thick path Shape that remains transparent. This is easily done by setting { stroke: "transparent", strokeWidth: 8 }. However, if you want to keep the original path Shape, both Shapes need to be declared as the "main" element for the Link by setting GraphObject.isPanelMain to true. This indicates to the Link panel that all such Shapes should get the same computed Geometry for the link path.

In this example, you will find it easier to select the link than it would be without the extra transparent link path shape.

The transparent shape can also be used for highlighting purposes. For example, to implement the effect of highlighting the link when the mouse passes over it, add GraphObject.mouseEnter and GraphObject.mouseLeave event handlers:

Pass the mouse over the link to see the effect. Such feedback also helps the user click or context click on the link.

Short lengths

Note that in the example above with the thick black path shape, the arrowhead seems to have disappeared due to the thickness of the link path. One can avoid the problem by increasing the GraphObject.scale of the arrowhead, perhaps to 2. This would make the arrowhead clearly visible, but would in turn show that the arrowhead is still obscured at the very end of the link path, where it is too wide to show the point of the arrowhead.

That problem can be avoided by setting Link.toShortLength to a value such as 8, depending on the kind of arrowhead used. The path geometry will be shortened by that distance so that the link path does not interfere with the arrowhead. This example shows the before and after of this change.

There is also a Link.fromShortLength property to control how far the "from" end of the link path is drawn. If there is an end segment, the distance that it can be shortened is limited to the corresponding Link.toEndSegmentLength or Link.fromEndSegmentLength. Note also that the short length may be negative, which would cause the link path to be drawn longer -- into the port at which the link is connected.

The normal expectation is that one cannot have a link relationship unless it connects two nodes. However, GoJS does support the creation and manipulation of links that have either or both of the Link.fromNode and Link.toNode properties with null values. This is demonstrated by the Draggable Link sample.

Both ends of the link must be connected to nodes in order for the standard link routing to operate. If a link does not know where to start or where to end, it cannot compute a route or a position for the link. However, you can provide a route by setting or binding Link.points to a list of two or more Points. That will automatically give the link a position so that it can be seen in the diagram.

The linking tools, LinkingTool and RelinkingTool, normally do not permit the creation or reconnection of links that connect with "nothing". However, you can set LinkingBaseTool.isUnconnectedLinkValid to true to allow the user to do so, as the Draggable Link sample demonstrates.

Links cannot normally be dragged unless they are part of a collection that includes the connected nodes. However, you can set DraggingTool.dragsLink to true to allow the user to drag a solitary Link. This mode allows the user to disconnect a link by dragging it away from the node(s)/port(s) to which it was attached. It also allows the user to reconnect one or both ends of the link by dropping it so that the end(s) are at valid port(s). This is demonstrated by the Draggable Link sample.

Further Reading