Skip to main content
  1. Index

Diagram Layouts

A "layout" is a way of sizing and positioning a collection of nodes and links. If you set Diagram.layout, that layout will be performed automatically as nodes or links are added or removed in the diagram, or as nodes change size. If you want to let your users position all parts manually, you don't need to set Diagram.layout.

GoJS offers several kinds of built-in automatic layouts, including:

In addition there are many custom layouts in the extensions and in the samples.

Grid Layout

This is a simple layout for placing Nodes in a grid-like arrangement. By default the layout will be performed again as the diagram's host div changes width.

See the GridLayout Sample for a demonstration of layout options. The Swim Lanes sample demonstrates a customization of GridLayout. See more samples that make use of GridLayout in the samples index.

Tree Layout

This layout positions nodes of a tree-structured graph in layers, either rows or columns depending on the TreeLayout.angle.

See the TreeLayout sample for a demonstration of layout options. The Org Chart Editor, Parse Tree, Layer Bands, and Virtualized Tree samples demonstrate customization of TreeLayout. See more samples that make use of TreeLayout in the samples index.

Force-Directed Layout

This layout treats the graph as if it were a system of physical bodies with forces acting on them and between them. Links between Nodes are treated as if they were springs.

See the ForceDirectedLayout sample for a demonstration of layout options. That sample also demonstrates a simple customization of ForceDirectedLayout. The Virtualized Force Directed sample demonstrates a more complicated customization of ForceDirectedLayout. See more samples that make use of ForceDirectedLayout in the samples index.

Layered Digraph Layout

This arranges nodes of directed graphs into layers, rows or columns depending on the LayeredDigraphLayout.direction. Unlike TreeLayout, this works not only with tree-structured graphs, but with any graph, although it's best with directed acyclic graphs.

See the LayeredDigraphLayout sample for a demonstration of layout options. The Genogram sample demonstrates a complex customization of LayeredDigraphLayout. See more samples that make use of LayeredDigraphLayout in the samples index.

Circular Layout

This layout positions nodes in a circular or elliptical arrangement.

See the CircularLayout sample for a demonstration of layout options. The Friend Wheel sample demonstrates a simple customization of CircularLayout. See more samples that make use of CircularLayout in the samples index.

Custom Layouts

GoJS encourages creation of custom layouts. The learn page on extensions gives a simple example of a custom layout. See more samples that make use of custom layouts in the samples index.

There are also many layouts that are extensions -- not predefined in the go.js or go-debug.js library, but available as source code in one of the two extension directories, with some documentation, and with corresponding samples.

Routing

Layouts also may also result in custom routing of the links, by setting properties on each Link. For example TreeLayout also ensures that links are routed in the expected direction by setting Link.fromSpot and Link.toSpot depending on the TreeLayout.angle. However, that behavior can be disabled by setting TreeLayout.setsPortSpot and TreeLayout.setsChildPortSpot. The same is true for some other layouts.

More general routing behaviors are implemented by Routers. See Routers for more details.

Layout Invalidation

A layout is considered "valid" when it has performed its positioning of its nodes and perhaps routed its links. However some kinds of changes cause a layout to become "invalid", thereby causing it to be performed again in the near future. Because layouts can be computationally expensive, automatic layouts are not performed as soon as a layout is invalidated. Instead they are typically performed at the end of a transaction.

The most common reasons for a layout to be invalidated are because a node or a link has been added or removed from the collection of nodes and links that a layout is responsible for, or because a node or a link has changed visibility, or because a node has changed size. If you do not want an automatic layout to happen when such a change occurs, it may be easiest to set Layout.isOngoing to false.

Another common situation is where you have set Diagram.layout to some kind of layout but you want to load a diagram (model) that contains manually positioned or adjusted node locations. The Binding of Part.location to the model data is effective, but the locations are lost when a layout is performed immediately after loading. This situation can be avoided by setting Layout.isInitial to false. After the initial layout the layout might still be invalidated by adding or removing or changing the visibility of a node or a link or by a change in node size, unless you have also set Layout.isOngoing to false. When both Layout.isInitial and Layout.isOngoing are false, you can still explicitly cause a layout to happen by either calling Layout.invalidateLayout or by calling Diagram.layoutDiagram with a true argument.

For example, in diagram editors it is commonplace to have TwoWay Bindings on Node.location to save manually adjusted node locations. This means that saved models will have saved locations for all of the nodes. But if you create a new model without all of the node data objects having real locations, you will want a layout to be performed initially when the model is loaded. You can accomplish this by setting Layout.isInitial to false (and optionally Layout.isOngoing to false, if that is what you want when users add or remove nodes or links) and then implementing an "InitialLayoutCompleted" DiagramEvent listener that decides whether a layout is needed. The decision could be to look at a flag that you add to the Model.modelData. Or you could look at all of the nodes to make sure their locations have real values:

js

But if you do not want a change to a particular Node or Link to cause an automatic layout, yet you do want that invalidation for other Nodes or Links, you can set the Part.layoutConditions property to the combination of Part "Layout..." flags that suits your needs. It is most common to not want a layout for the LayoutConditions.NodeSized condition:

js

Parts that remain not visible or that are in layers that are Layer.isTemporary also never invalidate any Layout.

Finally, you can set Part.isLayoutPositioned to false in order for the Layout to completely ignore that Part. But you will have to make sure that that Part does have a real Part.location, since no layout will set it for you. Without a real location the part will not be visible anywhere in the diagram. Furthermore if a node has isLayoutPositioned set to false, Layouts will not only ignore that node but also all links connecting with that node. Because the node will not be moved by the layout, it might overlap with the laid-out nodes and links. You can also set or bind Part.isLayoutPositioned to false on Links in order to have the layout ignore those links. This is demonstrated in Org Chart Extras.