Control the layout

This guide shows you how to steer Beck's automatic layout when the default arrangement isn't quite what you want.

Note

direction, rank/order pinning, and spacing.rank steer the layered engine — architecture, state, and class. A sequence uses a fixed grid and ignores them; there, only fit and spacing.node apply.

Beck lays diagrams out for you, Sugiyama-style: it ranks nodes along the flow, orders them within each rank to minimise edge crossings, then routes edges orthogonally around the cards. You rarely place anything by hand. The recipes below adjust that machinery — set the axis, loosen or tighten the spacing, and, when the auto-layout still puts a node in the wrong place, pin it.

Set the direction

To change the primary axis, set meta.direction. The default is TB (top-to-bottom); the others are BT, LR (left-to-right), and RL. The direction decides which way ranks progress — everything else (ordering, routing) follows from it.

yaml

type: architecture
meta: { direction: LR }
nodes:
  - { id: web, title: Web App, kind: user }
  - { id: api, title: API, kind: gateway }
  - { id: db, title: Postgres, kind: db }
edges:
  - { from: web, to: api }
  - { from: api, to: db, label: queries }
  

beck

Tune the spacing

To loosen or tighten the diagram, set meta.spacing. It takes three keys: rank (the gap along the flow), node (the gap across a rank), and cornerRadius (edge and card corner radius in px, default 16). The gap defaults depend on the diagram type: architecture and sequence default to rank: 96 / node: 32, while state and class — which pack many small, labelled nodes — default roomier at rank: 130 / node: 72 so their transition labels and self-loops have space to breathe. Set the keys explicitly to override either.

Give a busy diagram more room to breathe:

yaml

type: architecture
meta: { direction: LR, spacing: { rank: 140, node: 56, cornerRadius: 24 } }
nodes:
  - { id: gw, title: Gateway, kind: gateway }
  - { id: svc, title: Service }
  - { id: db, title: Postgres, kind: db }
edges:
  - { from: gw, to: svc }
  - { from: svc, to: db }
  

beck

Or pack a compact one tighter:

yaml

type: architecture
meta: { direction: LR, spacing: { rank: 64, node: 20, cornerRadius: 6 } }
nodes:
  - { id: gw, title: Gateway, kind: gateway }
  - { id: svc, title: Service }
  - { id: db, title: Postgres, kind: db }
edges:
  - { from: gw, to: svc }
  - { from: svc, to: db }
  

beck

Fit a wide diagram to the page

By default a diagram that is wider than its container scales down to fit, so it never overflows the page. On a narrow screen a large diagram can become too small to read. Set meta.fit: scroll to keep it at full size and let the container scroll sideways instead:

yaml

meta:
  fit: scroll   # `shrink` (the default) scales to fit; `scroll` keeps full size

In scroll mode the diagram stays at its natural width and a horizontal scrollbar appears only when the page is too narrow to show all of it; on a wide page it simply centres as usual. Vertical size is never constrained either way — only the horizontal axis differs.

Pin a node to a rank

When the auto-layout isn't what you want, override it per node. node.rank forces a node onto a specific layer; node.order tie-breaks left-to-right (or top-to-bottom) within a rank.

Here a metrics sink has no outgoing edge, so Beck ranks it next to the service that feeds it. Pinning metrics to rank 2 pushes it out to its own layer alongside the database, where it reads as a downstream consumer rather than a sibling of the service:

yaml

type: architecture
meta: { direction: LR }
nodes:
  - { id: gw, title: Gateway, kind: gateway }
  - { id: svc, title: Service }
  - { id: db, title: Postgres, kind: db, rank: 2 }
  - { id: metrics, title: Metrics, icon: metrics, rank: 2, order: 1 }
edges:
  - { from: gw, to: svc }
  - { from: svc, to: db }
  - { from: svc, to: metrics }
  

beck

Tip

Reach for rank/order only when the automatic placement is wrong — a handful of pins go a long way, and over-pinning fights the crossing-reduction pass that makes diagrams readable.

Nudge edge routing

If an edge leaves or arrives on the wrong face of a card, pin its anchors with fromSide/toSide (top bottom left right) rather than moving the nodes. See Connect and route edges for the full routing recipes.

For the complete meta and node field lists, see the YAML schema reference. To draw a boundary around related nodes — which also influences how they rank together — see Group related nodes.