routers

Routers take an array of link vertices and transform them into an array of route points that the link should go through. You can find more information in the correspondent learn section.

JointJS also contains mechanisms to define one's own custom routers.

Built-in routers

manhattan

The 'manhattan' router is the smart version of the 'orthogonal' router. It connects vertices with orthogonal line segments, inserting route points when necessary, while avoiding obstacles in its way. The router has useful options that determine how the algorithm behaves. These options can be passed as the router.args property:

step	number	Size of the imaginary grid followed by the 'manhattan' pathfinding algorithm. Lower number -> higher complexity. The 'manhattan' router performs best when step has the same value as dia.Paper.option.gridSize. Default is 10.
padding	number | object	Padding applied around start/end elements and obstacles. Default is the step value (see above). The util.normalizeSides function is used to understand the provided value. A single number is applied as padding to all sides of the elements. An object may be provided to specify values for left, top, right, bottom, horizontal and/or vertical sides.
maximumLoops	number	The maximum number of iterations of the pathfinding loop. If the number of iterations exceeds this maximum, pathfinding is aborted and the fallback router ('orthogonal') is used instead. Higher number -> higher complexity. Default is 2000.
maxAllowedDirectionChange	number	Maximum change of direction of the 'manhattan' route, in degrees. Default is 90.
perpendicular	boolean	Should the linkView.perpendicular option be in effect? This causes the router not to link precisely to the anchor of the end element but rather to a point close by that is orthogonal. This creates a clean connection between the element and the first/last vertex of the route. Default is true.
excludeEnds	Array<string>	An array with strings 'source' and/or 'target' that tells the algorithm that the given end element(s) should not be considered as an obstacle. Default is [] (both are considered obstacles).
excludeTypes	Array<string>	An array of element types that should not be considered obstacles when calculating the route. Default is ['basic.Text'].
startDirections	Array<string>	An array that specifies the possible starting directions from an element. Change this in situations where you need the link to, for example, always start at the bottom of the source element (then, the value would be ['bottom']). Default is ['left', 'right', 'top', 'bottom'] (all directions allowed).
endDirections	Array<string>	An array that specifies the possible ending directions to an element. Change this in situations where you need the link to, for example, always end at the bottom of the source element (then, the value would be ['bottom']). Default is ['left', 'right', 'top', 'bottom'] (all directions allowed).
isPointObstacle	(point) => boolean	A function that determines whether a given point is an obstacle or not. If used, the padding, excludeEnds and excludeTypes options are ignored.
fallbackRouter	(vertices, options, linkView) => Array<g.Point>	A function that is called when the routing fails. Use this in situations where you need to retry routing with more relaxed options e.g. no start/endDirections constraints. The default fallbackRouter is an orthogonal router.

Example:

link.router('manhattan', {
    excludeEnds: ['source'],
    excludeTypes: ['myNamespace.MyCommentElement'],
    startDirections: ['top'],
    endDirections: ['bottom']
});

metro

The 'metro' router is a modification of the 'manhattan' router that produces an octolinear route (i.e. a route consisting of orthogonal and diagonal line segments, akin to the London Underground map design). It also avoids obstacles, and accepts the same router.args as 'manhattan', with a few modifications:

maximumLoops	number	Does not use the 'orthogonal' router as fallback if path cannot to be found in the given number of iterations. Instead, a custom octolinear fallback route is used that does not avoid obstacles.
maxAllowedDirectionChange	number	Default changes to 45.
startDirection	Array<string>	Same as 'manhattan' (i.e. only the four orthogonal directions are accepted as start directions).
endDirection	Array<string>	Same as 'manhattan' (i.e. only the four orthogonal directions are accepted as end directions).

Example:

link.router('metro', {
    excludeEnds: ['source'],
    excludeTypes: ['myNamespace.MyCommentElement'],
    startDirections: ['top'],
    endDirections: ['bottom']
});

normal

The 'normal' router is the default router for links and it is the simplest router. It does not have any options and it does not do anything; it returns the vertices passed to it without modification as the route to be taken.

Example:

link.router('normal');

orthogonal

The 'orthogonal' router returns a route with orthogonal line segments. It generates extra route points in order to create the right angles on the way. It does not avoid obstacles. The router has one optional argument; this can be passed as the router.args.elementPadding property:

padding	number | object	The minimum distance from element at which the first/last route angle may be placed. Default is 20. The util.normalizeSides function is used to understand the provided value. A single number is applied as padding to all sides of the elements. An object may be provided to specify values for left, top, right, bottom, horizontal and/or vertical sides.

Example:

link.router('orthogonal', {
    padding: 10
});

rightAngle

The 'rightAngle' router returns a route with orthogonal line segments just like 'orthogonal' router, except it chooses the direction of the link based on the position of the source and target anchors (or port position). This router avoids collisions with source and target elements, but does not avoid other obstacles. The behavior of the router can be modified by passing optional arguments:

This router completely ignores vertices, so using vertex tools such as linkTools.Vertices will not result in any change of path.

margin	number	The minimum distance between the route and the element. The default is 20.
sourceDirection	rightAngle.Directions	The direction of the link from the source anchor. The default is rightAngle.Directions.AUTO.
targetDirection	rightAngle.Directions	The direction of the link from the target anchor. The default is rightAngle.Directions.AUTO.

Example:

link.router('rightAngle', {
    margin: 10,
    sourceDirection: routers.rightAngle.Directions.TOP,
    targetDirection: routers.rightAngle.Directions.BOTTOM
});

Directions

Available values for the sourceDirection and targetDirection options:

rightAngle.Directions.AUTO	It automatically decides which direction to use. If the link is connected to a port, the rightAngle.Directions.MAGNET_SIDE is used. Otherwise, it uses rightAngle.Directions.ANCHOR_SIDE.
rightAngle.Directions.ANCHOR_SIDE	Determines the direction depending on the side of the magnet where the anchor is located.
rightAngle.Directions.MAGNET_SIDE	Determines the direction depending on the side of the element where the magnet (e.g. port) is located.
rightAngle.Directions.LEFT	Sets the direction of the link to the left side.
rightAngle.Directions.RIGHT	Sets the direction of the link to the right side.
rightAngle.Directions.TOP	Sets the direction of the link to the top side.
rightAngle.Directions.BOTTOM	Sets the direction of the link to the bottom side.