#cy.layout(options)
// Make a layout over the whole graph
cy.layout(options: LayoutOptions): LayoutMake a layout over the whole graph. The layout does not run until you call .run() on it.
Built-ins: grid, preset, circle, concentric, breadthfirst, random, radial, pack, force (the GPU-capable spring–electric layout) and flow (the layered layout) — the set schemas/layout-options.schema.json describes. An external layout is passed directly rather than registered — without a string registry — by giving impl: a class or object implementing { run( ctx), stop?() } (see layout/contract.mts for the LayoutContext it receives).
Lifecycle events (layoutstart/layoutready/layoutstop) fire on the core, once per run; layout instances are not emitters.
| Name | Description |
|---|---|
options: LayoutOptions |
|
Fields of options
| Name | Description |
|---|---|
name: undefined? | |
avoidOverlap: boolean? | separate nodes by their extents (default true) — bodies, plus
labels when |
avoidOverlapPadding: number? | extra room around each body (default 0 — |
condense: boolean? | size the rings by their nodes rather than by the box (125.3,
grid's spelling): every ring takes the smallest radius that
clears its own nodes and the ring inside it at
|
rows: number? | |
cols: number? | |
position: (node: unknown) => { row?: number; col?: number } | undefined? | returns a fixed { row, col } for a node handle |
sort: LayoutSortMapping | ((a: unknown, b: unknown) => number)? | the order around the circle: a |
eles: unknown? | the elements to lay out (set automatically by |
fit: boolean? | |
padding: number? | |
boundingBox: BoundingBoxInput? | |
nodeDimensionsIncludeLabels: boolean? | include labels in the node dimensions a layout spaces by — default
|
spacingFactor: number? | |
transform: (node: unknown, position: Position) => Position? | transform a computed position (e.g. to flip an axis) |
animate: boolean? | whether to animate node positions into place |
animationDuration: number? | |
animationEasing: string? | |
animateFilter: (node: unknown, i: number) => boolean? | which nodes animate (others jump); all by default |
ready: () => void? | callback on layoutready |
stop: () => void? | callback on layoutstop |
zoom: number? | zoom to set when fit is false |
pan: Position? | pan to set when fit is false |
packComponents: boolean? | lay each disconnected component out on its own — one ring, one grid, one tree per component — and shelf-pack the results largest first (default false: one drawing about one centre). Locked nodes are left out and the packed field is moved off their boxes. |
componentSpacing: number? | the gap between packed disconnected components (default 40) |
componentGroup: ( component: LayoutComponentInfo, ) => string | number | null | undefined? | group the packed components (121.1): called once per component with its description, and the components sharing a key pack on their own, the groups standing in a row left to right by key — numbers ascending, then strings, then the unkeyed. |
componentOrder: (a: LayoutComponentInfo, b: LayoutComponentInfo) => number? | the order the pack lays components out in, a comparator over two descriptions ahead of largest-first (121.1). |
groupSpacing: number? | the gap between the groups' packed boxes (default three
|
positions: | Record<string, Position> | ((node: unknown) => Position | null | undefined)? | node id → position map, or a function of a node handle; absent nodes keep their position |
radius: number? | the circle's radius (computed when omitted) |
startAngle: number? | where the sweep begins, in radians (default 3π/2 — up) |
sweep: number? | the total angle the trees share, in radians (default 2π) |
clockwise: boolean? | wedge order runs clockwise (default true) |
counterclockwise: boolean? | |
equidistant: boolean? | whether levels are an equal radial distance apart |
minNodeSpacing: number? | min spacing between node outsides (radius adjustment) |
height: number? | height/width of the layout area (override the container) |
width: number? | |
concentric: LayoutScoreMapping | ((node: unknown) => number)? | the score deciding ring membership — higher sits closer to the
center (default: degree). A |
levelWidth: (nodes: unknown) => number? | the variation of concentric values per level (default: maxDegree / 4) |
directed: boolean? | whether the tree is directed downwards (default false) |
direction: 'downward' | 'upward' | 'leftward' | 'rightward'? | drawing direction of the flow (default 'downward') |
circle: boolean? | put depths in concentric circles instead of rows |
grid: boolean? | place the DAG on an even grid (circle: false only) |
roots: unknown? | the tree roots: a collection or an array of node ids (never a selector string); omitted, a component's roots are the nodes with no incoming edge (125.3 — radial is a hierarchy's picture), or its maximum-degree nodes when it has none (a cycle) — maximum degree alone before 125.3 |
depthSort: LayoutSortMapping | ((a: unknown, b: unknown) => number)? | the order within a depth: a |
maximal: boolean? | shift nodes down to their maximal depths (DAGs only) |
acyclic: boolean? | the graph is known acyclic: skip cycle removal (default false) |
seed: number? | |
levelSpacing: number? | the ring gap in model px; derived from the bounding box unset.
A floor under |
weight: 'leaves' | 'subtree'? | what sizes a subtree's wedge: its leaf count (default) or its whole node count |
edgeLength: number | LayoutScoreMapping | ((edge: unknown) => number)? | ideal edge length: a number; a |
repulsion: number? | |
stiffness: number? | |
gravity: number? | |
decay: number? | alpha annealing rate per iteration |
iterations: number? | |
threshold: number? | convergence: settled when max displacement stays under this |
randomize: boolean? | fresh seeded scatter (default) vs relaxing current positions |
animateLive: boolean? | stream the run: positions land per frame while the sim runs (the
pre-114 |
infinite: boolean? | the run has no end of its own (118.3): it streams like
|
stepsPerFrame: number? | iterations per animation frame (animateLive: true; default 3) |
executor: 'auto' | 'cpu' | 'gpu' | 'workers'? | where the simulation runs (default |
init: 'spectral' | 'scatter'? | what a fresh placement is (59.4): 'spectral' (the default —
landmark-MDS per component, the global untangling) or 'scatter'
(the plain seeded scatter). Ignored under |
nestingFactor: number? | ideal-length multiplier per compound boundary an edge spans (length × levels × nestingFactor; default 1.2) |
gravityCompound: number? | the compound centroid pull, as a multiple of |
alignment: { horizontal?: string[][]; vertical?: string[][] }? | alignment constraints (85.2, fcose's shape): |
relativePlacement: ( | { left: string; right: string; gap?: number } | { top: string; bottom: string; gap?: number } )[]? | relative-placement constraints (85.2): keep |
nodeSep: number? | px gap between adjacent nodes in a rank (default 50): between their boxes' facing sides, each node's own extent on that side (125.2 — a label hung to one side of its body extends that side alone), and along the rank's axis for the direction (a rightward rank is separated by heights) |
rankSep: number? | px gap between rank rows (default 60): a row reaches as far from its centre line as its nodes' extents on each side, and a taxi edge's turn lands inside this band, which the layout keeps node-free |
edgeSep: number? | px per taxi track a rank gap grows to hold (default 10, round
124.5): the gap below a rank becomes |
layering: 'network-simplex' | 'longest-path' | 'auto'? | rank assignment: 'network-simplex' (GKNV — fewest long edges, default), 'longest-path' (O(V+E), the huge-graph fast path), or 'auto' (simplex up to ~50k nodes, then longest-path) |
thoroughness: number? | crossing-minimization effort, 1..10 (default 7): scales the sweep and transpose budgets |
minLength: number | LayoutScoreMapping | ((edge: unknown) => number)? | minimum ranks an edge must span (default 1): a number, a
|
edgeWeight: number | LayoutScoreMapping | ((edge: unknown) => number)? | edge straightening weight (default 1): heavier edges pull straighter through crossing minimization and coordinates — a number, a score mapping, or a fn of the edge handle |
cycleRemoval: 'greedy' | 'dfs'? | which arcs flip on cycles: 'greedy' (Eades–Lin–Smyth bound, default) or 'dfs' (input order dominates) |
rankConstraints: { min?: string[]; max?: string[]; same?: string[][] }? | rank constraints as id lists (never selector strings): |
impl: unknown |
Layoutthe layout instance, unstarted
Example
const handle = cy.layout({ name: 'grid', fit: false });handle.run();console.log(cy.nodes().length); // 3if neither a known name nor an impl is given
Also spelled cy.makeLayout, cy.createLayout.
Collection#layout to lay out a subset