MSAGL

@joint/layout-msagl integrates the Microsoft Automatic Graph Layout (MSAGL) layered layout with JointJS. The package exposes the layout() function together with helper types for configuring the Sugiyama router.

See the learn section for installation steps and examples.

Functions

layout()

layout(graphOrCells: dia.Graph | dia.Cell[], options?: Options): LayoutResult;

Rearranges the provided JointJS graph or an array of cells using the MSAGL Sugiyama algorithm and returns a LayoutResult. The bbox field accounts for the tight bounding box of the laid out graph and the fields msGraph and msGeomGraph can be utilized to interact with the underlying MSAGL objects, you can find more information about them in the MSAGL documentation.

Options

Option	Type	Description
layerDirection	LayerDirectionEnum	Controls the direction in which MSAGL stacks layers. Defaults to LayerDirectionEnum.TB.
layerSeparation	number	Sets the minimum vertical gap between successive layers. Defaults to 40.
nodeSeparation	number	Sets the minimum horizontal gap between nodes that belong to the same layer. Defaults to 20.
polylinePadding	number	Adds extra clearance between routed polylines and element boundaries. Defaults to 1.
rectilinearSelfEdgeOffset	number	Offsets rectilinear self-loops vertically so they stay clear of the source element. Defaults to 10.
gridSize	number	Grid size for routing; applied to X and Y. Set 0 to disable snapping. Defaults to 0.
edgeRoutingMode	EdgeRoutingMode	Switches between orthogonal (Rectilinear) and bundled spline (SplineBundling) routing. Defaults to EdgeRoutingMode.Rectilinear.
x	number	Controls the x coordinate of the top-level graph origin. Defaults to 0.
y	number	Controls the y coordinate of the top-level graph origin. Defaults to 0.
clusterPadding	dia.Sides	Padding reserved inside subgraph clusters. Pass a number for uniform padding or an object for per-side values. Defaults to 10.
getSize	(element: dia.Element) => dia.Size	Returns the element size MSAGL should use during layout. Defaults to element.size().
getLabelSize	(cell: dia.Cell) => dia.Size | undefined	Provides label dimensions so edges and subgraphs reserve space. Defaults to cell.get('labelSize'); return undefined to ignore a label.
setPosition	(element: dia.Element, position: dia.Point) => void	Invoked with each element's new top-left position. Defaults to element.position(x, y).
setVertices	boolean | (link: dia.Link, vertices: dia.Point[]) => void	Controls whether links are updated with the (sampled) vertices. Defaults to true (calls link.vertices(vertices)). Pass false to keep existing routing. If the option is defined as a function it will be used to set the vertices of links at the end of the layout. This is useful if you don't want to use the default but want to set the vertices in an animated fashion via transitions.
setLabels	boolean | (link: dia.Link, labelBBox: dia.BBox, points: dia.Point[]) => void	Applies computed label geometry along the routed edge. Defaults to updating the first label via distance/offset; pass false to skip.
setAnchor	boolean | (link: dia.Link, linkEndPoint: dia.Point, bbox: dia.BBox, endType: 'source' | 'target') => void	Adjusts link anchors to match MSAGL entry/exit points. Defaults to assigning the modelCenter anchor; pass false to skip.
setClusterSize	(element: dia.Element, size: dia.Size) => void	Sets the size of a cluster. Defaults to element.size(size).

Types

EdgeRoutingMode

enum EdgeRoutingMode {
    SplineBundling = 1,
    Rectilinear = 4
}

SplineBundling enables smooth bundled splines, while Rectilinear routes orthogonal polylines (the default).

GetLabelSizeCallback

type GetLabelSizeCallback = (cell: dia.Cell) => dia.Size | undefined;

GetSizeCallback

type GetSizeCallback = (element: dia.Element) => dia.Size;

LayerDirectionEnum

enum LayerDirectionEnum {
    TB,
    LR,
    BT,
    RL
}

Use TB, BT, LR, or RL to control the top-level flow direction.

LayoutResult

interface LayoutResult {
    bbox: g.Rect;
    msGraph: msagl.Graph;
    msGeomGraph: msagl.GeomGraph;
}

Options

interface Options {
    layerDirection?: layout.MSAGL.LayerDirectionEnum;
    layerSeparation?: number;
    nodeSeparation?: number;
    polylinePadding?: number;
    rectilinearSelfEdgeOffset?: number;
    gridSize?: number;
    edgeRoutingMode?: layout.MSAGL.EdgeRoutingMode;
    x?: number;
    y?: number;
    clusterPadding?: dia.Sides;
    getSize?: layout.MSAGL.GetSizeCallback;
    getLabelSize?: layout.MSAGL.GetLabelSizeCallback;
    setPosition?: layout.MSAGL.SetPositionCallback;
    setVertices?: boolean | layout.MSAGL.SetVerticesCallback;
    setLabels?: boolean | layout.MSAGL.SetLabelsCallback;
    setAnchor?: boolean | layout.MSAGL.SetAnchorCallback;
    setClusterSize?: layout.MSAGL.SetClusterSizeCallback;
}

SetAnchorCallback

type SetAnchorCallback = (link: dia.Link, linkEndPoint: dia.Point, bbox: dia.BBox, endType: 'source' | 'target') => void;

SetClusterSizeCallback

type SetClusterSizeCallback = (element: dia.Element, size: dia.Size) => void;

SetLabelsCallback

type SetLabelsCallback = (link: dia.Link, labelBBox: dia.BBox, points: dia.Point[]) => void;

SetPositionCallback

type SetPositionCallback = (element: dia.Element, position: dia.Point) => void;

SetVerticesCallback

type SetVerticesCallback = (link: dia.Link, vertices: dia.Point[]) => void;