New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

Constraints

Constraints declaratively control element positioning. Add them to the constraints array in a scene document or via the addConstraint operation. order applies when the engine lays the nodes out (order); the other types apply to the drawing on every save, and leave the positions kept in the nodes’ layout as they are.

Each constraint has a type and type-specific parameters. An id is optional; give one to a constraint you may want to remove, since removeConstraint removes a constraint by its id. IDs are unique among a diagram’s constraints: a second constraint with the same id is the error CONSTRAINT_ID_DUPLICATE.

Every element a constraint names must exist. Deleting an element removes the constraints that name it as their container, source or target, and those left with fewer elements than they need (two, or one for contain and centerIn); any other constraint just loses the deleted element. The edit’s warnings say which constraints went.

align

Align elements along a single axis by their centers.

{
  "id": "c1",
  "type": "align",
  "axis": "y",
  "elements": ["btn1", "btn2", "btn3"]
}
ParameterRequiredDescription
axisYes"x" or "y" - axis to align on
elementsYesElement IDs to align

Elements are moved so their centers share the same coordinate on the specified axis.

distribute

Space elements evenly along an axis.

{
  "id": "c2",
  "type": "distribute",
  "axis": "x",
  "elements": ["icon1", "icon2", "icon3", "icon4"],
  "gap": 20
}
ParameterRequiredDescription
axisYes"x" or "y" - distribution direction
elementsYesElement IDs to distribute
gapNoPixel spacing between elements (default: 0)

The engine sorts the elements by position along axis, keeps the first where it is, and puts each next one gap pixels after the one before.

stack

Stack elements sequentially along one axis.

{
  "id": "c3",
  "type": "stack",
  "axis": "y",
  "elements": ["title", "description", "button"],
  "gap": 8
}
ParameterRequiredDescription
axisYes"x" or "y" - stacking direction
elementsYesElement IDs to stack
gapNoPixel spacing between elements (default: 0)

First element stays in place. Each subsequent element is positioned directly after the previous one.

grid

Arrange elements in a grid layout.

{
  "id": "c4",
  "type": "grid",
  "elements": ["a", "b", "c", "d", "e", "f"],
  "columns": 3,
  "columnGap": 16,
  "rowGap": 16
}
ParameterRequiredDescription
elementsYesElement IDs to arrange
columnsNoNumber of columns (default: 2)
columnGapNoHorizontal spacing (default: 0)
rowGapNoVertical spacing (default: 0)

Elements are laid out left-to-right, top-to-bottom. The first element’s position is the grid origin.

sameSize

Make elements the same dimensions.

{
  "id": "c5",
  "type": "sameSize",
  "elements": ["btn1", "btn2", "btn3"],
  "dimension": "width"
}
ParameterRequiredDescription
elementsYesElement IDs to resize
dimensionNo"width", "height", or "both" (default: "both")

The first element’s size is used as the reference.

contain

Set a container’s box to its elements’ bounding box plus padding. The box can shrink as well as grow.

{
  "id": "c6",
  "type": "contain",
  "containerId": "group1",
  "elements": ["node1", "node2", "node3"],
  "padding": 20
}
ParameterRequiredDescription
containerIdYesContainer element ID to resize
elementsYesChild element IDs that must fit inside
paddingNoPixel padding around children (default: 0)

The container is resized to the bounding box of all children, plus padding.

centerIn

Center elements inside a container.

{
  "id": "c7",
  "type": "centerIn",
  "containerId": "header",
  "elements": ["logo"]
}
ParameterRequiredDescription
containerIdYesContainer element ID
elementsYesElement IDs to center

Each element is centered on both axes.

minGap

Enforce minimum spacing between elements.

{
  "id": "c8",
  "type": "minGap",
  "axis": "y",
  "elements": ["item1", "item2", "item3"],
  "gap": 8
}
ParameterRequiredDescription
axisYes"x" or "y" - spacing direction
elementsYesElement IDs to check
gapYesMinimum pixel gap required

Elements that are closer than the minimum gap are pushed apart.

noOverlap

Prevent elements from overlapping.

{
  "id": "c9",
  "type": "noOverlap",
  "elements": ["label1", "label2", "label3"]
}
ParameterRequiredDescription
elementsYesElement IDs to check

Overlapping elements are shifted apart horizontally.

order

Hard ordering constraint enforced during auto-layout. Controls which rank (layer) a node lands on and its position within a rank.

{
  "id": "c10",
  "type": "order",
  "source": "db",
  "target": "api",
  "relation": "rightOf"
}
ParameterRequiredDescription
sourceYesElement ID of the source node
targetYesElement ID of the target node
relationYes"leftOf" | "rightOf" | "above" | "below" | "sameRank"

The relation describes the source relative to the target. For example, { source: "db", target: "api", relation: "rightOf" } places the database to the right of the API.

Along the flow (leftOf and rightOf in LR and RL, above and below in TB and BT) a relation sets the rank, the layer a node lands in. Across it, a relation sets the order of two nodes that share a rank. sameRank puts two nodes in the same layer. LR, the default direction, is a left-to-right flow, so there rightOf puts source in a later rank, and below puts it lower than target when they share one.

In a pool, the lanes keep the order the pool’s children list them in. A relation across the flow (such as below in LR) between two nodes in different lanes gives way to that order: it doesn’t move a node in an earlier lane past one in a later lane (Layout engine: Pools and lanes).

In an AWS diagram the cloud layout arranges, a relation orders two nodes within one row or column: leftOf and rightOf within a subnet’s row or AWS Cloud’s row, above and below within a Region’s column or an outside column. One between nodes of different rows or columns, and sameRank, is ignored. One an edit adds swaps its two nodes in their row or column when they stand the wrong way around and can simply trade places (Layout engine: AWS architecture diagrams).

In a Google Cloud diagram the cloud layout arranges, leftOf and rightOf order two nodes within one row: the global rows, a Region’s rows, a row of nodes in a subnet or the outside row. A tier’s cards stand in their zones’ columns, which no constraint changes, and above, below, sameRank and a relation between two rows are ignored. A leftOf or rightOf an edit adds swaps its two nodes in their row when they stand the wrong way around and can simply trade places. Where one is a load balancer over the gap between two Regions, it keeps its place and the other stands beside it in the order asked (Layout engine: Google Cloud architecture diagrams).

Applies when the engine places nodes: every node on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily (re-sending the current value changes nothing); and the two nodes of an order constraint added to a saved diagram, which the engine places again, in order, when they don’t already stand in that order. Nodes already in order, and every other node that has a position, keep it, except in an AWS or Google Cloud diagram, where placing the two can grow their row or column, or move an AWS Region’s column right as one to give a labeled line into it room (Layout engine: AWS architecture diagrams, Google Cloud architecture diagrams). On autoLayout without elements, or a changed layoutStrategy or diagramFamily, the members of a frame that keeps its own layout keep their positions: a pool, lane or fragment, and in org charts and networks any frame (every other frame drops its layout and is laid out with its members). The engine places the other nodes around them instead of laying out every node. Conflicting constraints (cycles) are detected and gracefully dropped rather than crashing the layout.

Adding and removing

In a saved diagram, add a constraint with the addConstraint operation and remove one by its id with removeConstraint (Operations: addConstraint).