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"]
}
| Parameter | Required | Description |
|---|---|---|
axis | Yes | "x" or "y" - axis to align on |
elements | Yes | Element 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
}
| Parameter | Required | Description |
|---|---|---|
axis | Yes | "x" or "y" - distribution direction |
elements | Yes | Element IDs to distribute |
gap | No | Pixel 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
}
| Parameter | Required | Description |
|---|---|---|
axis | Yes | "x" or "y" - stacking direction |
elements | Yes | Element IDs to stack |
gap | No | Pixel 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
}
| Parameter | Required | Description |
|---|---|---|
elements | Yes | Element IDs to arrange |
columns | No | Number of columns (default: 2) |
columnGap | No | Horizontal spacing (default: 0) |
rowGap | No | Vertical 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"
}
| Parameter | Required | Description |
|---|---|---|
elements | Yes | Element IDs to resize |
dimension | No | "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
}
| Parameter | Required | Description |
|---|---|---|
containerId | Yes | Container element ID to resize |
elements | Yes | Child element IDs that must fit inside |
padding | No | Pixel 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"]
}
| Parameter | Required | Description |
|---|---|---|
containerId | Yes | Container element ID |
elements | Yes | Element 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
}
| Parameter | Required | Description |
|---|---|---|
axis | Yes | "x" or "y" - spacing direction |
elements | Yes | Element IDs to check |
gap | Yes | Minimum 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"]
}
| Parameter | Required | Description |
|---|---|---|
elements | Yes | Element 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"
}
| Parameter | Required | Description |
|---|---|---|
source | Yes | Element ID of the source node |
target | Yes | Element ID of the target node |
relation | Yes | "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).