Skip to content

eles.layout(options)

eles.layout — Collection > Layout. Cytoscape.js signatures, parameters and return contract.

eles.layout — Collection › Layout

Preview · Collection › Layout

Read in the complete API reference · All API members

// A layout scoped to this collection
eles.layout(options: LayoutOptions): ReturnType<Core['layout']>

A layout scoped to this collection.

Parameters
NameDescription
options: LayoutOptions

the layout options, as cy.layout(); eles is set to this collection

Fields of options
NameDescription
name: undefined?
avoidOverlap: boolean?

separate nodes by their extents (default true) — bodies, plus labels when nodeDimensionsIncludeLabels is true (114.6); false places points, nodeSep / rankSep then centre to centre

avoidOverlapPadding: number?

extra room around each body (default 0 — nodeSep and rankSep own the spacing)

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 avoidOverlapPadding, so the gap is the option and the viewport only centres. Off (the default), the rings start at an even share of the box's shorter side (or levelSpacing) and only grow from there. Implies avoidOverlap.

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 { data, order? } sort mapping (canonical, serializable — 85.3) or a comparator over node handles

eles: unknown?

the elements to lay out (set automatically by eles.layout()); defaults to the whole graph

fit: boolean?
padding: number?
boundingBox: BoundingBoxInput?
nodeDimensionsIncludeLabels: boolean?

include labels in the node dimensions a layout spaces by — default false. Every built-in's overlap avoidance reads the same boxes, so true keeps labels apart too. Headless label dimensions are estimates.

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 componentSpacings)

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 { data, … } score mapping (canonical, serializable — 85.3) or a function of the node handle

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 { data, order? } sort mapping (canonical, serializable — 85.3) or a comparator over node handles

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 avoidOverlap: a ring grows past it when its nodes would otherwise touch

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 { data, scale?, range?, invert?, default? } score mapping (canonical, serializable — 85.3, e.g. { data: 'score', scale: 'log', range: [40, 200], invert: true } for large scores → short edges); or a plain fn of the edge handle. Resolved once at start either way

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 animate: true); takes precedence over animate

infinite: boolean?

the run has no end of its own (118.3): it streams like animateLive and then ticks only while the field is moving — at rest it costs nothing, and a drag, a position() write or an added / removed element (whole-graph scope) heats it back up; the grabbed node is pinned for the gesture and its neighbourhood reflows around it. layout.stop() ends it, landing the positions as they stand — no separation pass, no re-pack, no fit and no tween. avoidOverlap therefore means the per-tick sweep ('sim'); iterations is ignored; layout.reheat() is the handle for a change the run cannot see

stepsPerFrame: number?

iterations per animation frame (animateLive: true; default 3)

executor: 'auto' | 'cpu' | 'gpu' | 'workers'?

where the simulation runs (default 'auto'): 'auto' takes the GPU integrator where the renderer offers one, else the CPU simulation on a worker that loaded this same bundle wherever one can be constructed — headless included, so a Node process keeps its event loop free as a page keeps its UI thread (the run is then asynchronous: positions at layoutstop / promise()) — else in-thread. 'cpu' is the in-thread reference (bit-reproducible; the worker answers the same bits) and the synchronous spelling; 'workers' asks for the worker and throws at start where none can be constructed; 'gpu' throws at start where no integrator is available

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 randomize: false.

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 gravity (59.5; the Bilkent line's gravityCompound — default 1.5)

alignment: { horizontal?: string[][]; vertical?: string[][] }?

alignment constraints (85.2, fcose's shape): horizontal groups share a y coordinate, vertical groups an x — id arrays, serializable; groups sharing a node merge. A locked member pins its group. Constrained runs take the CPU executor.

relativePlacement: ( | { left: string; right: string; gap?: number } | { top: string; bottom: string; gap?: number } )[]?

relative-placement constraints (85.2): keep left at least gap px left of right (top/bottom likewise vertically); gap defaults to the run's mean ideal edge length.

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 max(rankSep, tracks × edgeSep + 20), where tracks is how many of that rank's fan-outs overlap on one line — the lines taxi-turn: auto draws; 0 leaves every gap at rankSep

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 { data, … } score mapping (85.3), or a fn of the edge handle

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): min pins to the first rank, max to the last, each same group to one shared rank

impl: unknown
Returns ReturnType<Core['layout']>

the layout instance; nothing runs until run()

Example

const handle = cy.nodes().layout({ name: 'grid', fit: false });
handle.run();
console.log(cy.nodes().length); // 3

Example graph and handle setup

Also spelled eles.makeLayout, eles.createLayout.