Skip to content

Position and dimensions

Read geometry and write node positions in the documented coordinate space.

#ele.position()

// Get the position
ele.position(): Position | undefined

Read the first element's position in model coordinates.

Returns Position | undefined

the first element's position, or undefined when empty

Example

console.log(cy.getElementById('a').position()); // { x: 0, y: 0 }

Example graph and handle setup

#ele.position(dim)

// Get one coordinate
ele.position(dim: string): number | undefined

Read one coordinate of the first element.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

Returns number | undefined

the first element's coordinate, or undefined when empty

Example

console.log(cy.getElementById('a').position('x')); // 0

Example graph and handle setup

#eles.position(position)

// Set the position
eles.position(position: Position): this

Set the position on every unlocked node.

Parameters
NameDescription
position: Position

the coordinates to write

Fields of position
NameDescription
x: number
y: number
Returns this

this collection, for chaining

Example

const result = eles.position({ x: 20, y: 10 });
console.log(result === eles); // true

Example graph and handle setup

#eles.position(dim, value)

// Set one coordinate
eles.position(dim: string, value: number): this

Set one coordinate on every unlocked node.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

value: number

the coordinate to write

Returns this

this collection, for chaining

Example

const result = eles.position('x', 20);
console.log(result === eles); // true

Example graph and handle setup

Also spelled eles.modelPosition, eles.point.

#eles.positions(pos)

// Set every node's position, from a constant or per-element function
eles.positions(pos: Position | ElePositionFn<NodeData, EdgeData, Data>): this

Set every node's position, from a constant or per-element function.

Parameters
NameDescription
pos: Position | ElePositionFn<NodeData, EdgeData, Data>

a { x, y } for all of them, or ( ele, i) => ( { x, y })

Fields of pos
NameDescription
x: number
y: number
Returns this

this collection, for chaining

Example

cy.nodes().positions((node, i) => ({ x: i * 50, y: 0 }));
console.log(cy.getElementById('b').position('x')); // 50

Example graph and handle setup

Also spelled eles.modelPositions, eles.points.

#eles.shift(dim, value?)

// Offset positions by a vector or along one axis
eles.shift(dim: string | Position, value?: number): this

Offset positions by a vector or along one axis.

Parameters
NameDescription
dim: string | Position

a { x, y } delta, or 'x' / 'y' with value

value: number?

the offset, when dim names an axis

Fields of dim
NameDescription
x: number
y: number
Returns this

this collection, for chaining

Example

cy.nodes().shift({ x: 10, y: 0 });
console.log(cy.getElementById('a').position('x')); // 10

Example graph and handle setup

#ele.relativePosition()

// Get the position
ele.relativePosition(): Position | undefined

Read the first element's position relative to its immediate compound parent. For orphans this equals the model position.

Returns Position | undefined

the first element's position, or undefined when empty

Example

console.log(cy.getElementById('a').relativePosition()); // { x: 0, y: 0 }

Example graph and handle setup

#ele.relativePosition(dim)

// Get one coordinate
ele.relativePosition(dim: string): number | undefined

Read one coordinate of the first element.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

Returns number | undefined

the first element's coordinate, or undefined when empty

Example

console.log(cy.getElementById('a').relativePosition('x')); // 0

Example graph and handle setup

#eles.relativePosition(position)

// Set the position
eles.relativePosition(position: Position): this

Set the position on every unlocked node.

Parameters
NameDescription
position: Position

the coordinates to write

Fields of position
NameDescription
x: number
y: number
Returns this

this collection, for chaining

Example

const result = eles.relativePosition({ x: 20, y: 10 });
console.log(result === eles); // true

Example graph and handle setup

#eles.relativePosition(dim, value)

// Set one coordinate
eles.relativePosition(dim: string, value: number): this

Set one coordinate on every unlocked node.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

value: number

the coordinate to write

Returns this

this collection, for chaining

Example

const result = eles.relativePosition('x', 20);
console.log(result === eles); // true

Example graph and handle setup

Also spelled eles.relativePoint.

#ele.renderedPosition()

// Get the position
ele.renderedPosition(): Position | undefined

Read the first element's position in rendered CSS pixels, after applying the graph's zoom and pan.

Returns Position | undefined

the first element's position, or undefined when empty

Example

cy.zoom(1); cy.pan({ x: 0, y: 0 });
console.log(cy.getElementById('a').renderedPosition()); // { x: 0, y: 0 }

Example graph and handle setup

#ele.renderedPosition(dim)

// Get one coordinate
ele.renderedPosition(dim: string): number | undefined

Read one coordinate of the first element.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

Returns number | undefined

the first element's coordinate, or undefined when empty

Example

cy.zoom(1); cy.pan({ x: 0, y: 0 });
console.log(cy.getElementById('a').renderedPosition('x')); // 0

Example graph and handle setup

#eles.renderedPosition(position)

// Set the position
eles.renderedPosition(position: Position): this

Set the position on every unlocked node.

Parameters
NameDescription
position: Position

the coordinates to write

Fields of position
NameDescription
x: number
y: number
Returns this

this collection, for chaining

Example

const result = eles.renderedPosition({ x: 20, y: 10 });
console.log(result === eles); // true

Example graph and handle setup

#eles.renderedPosition(dim, value)

// Set one coordinate
eles.renderedPosition(dim: string, value: number): this

Set one coordinate on every unlocked node.

Parameters
NameDescription
dim: string

the coordinate, 'x' or 'y'

value: number

the coordinate to write

Returns this

this collection, for chaining

Example

const result = eles.renderedPosition('x', 20);
console.log(result === eles); // true

Example graph and handle setup

Also spelled eles.renderedPoint.

#ele.width()

// Read the first element's width in model pixels: a node's content width, excluding padding and border, or an edge's stroke width
ele.width(): number | undefined

Read the first element's width in model pixels: a node's content width, excluding padding and border, or an edge's stroke width. A compound parent's width is derived from its children. The read reflects the current value during size animations.

Returns number | undefined

the width, or undefined when empty or removed

Example

console.log(eles.width()); // 30

Example graph and handle setup

See

Collection#outerWidth to include the border

#ele.height()

// Read the first element's height in model pixels: a node's content height, excluding padding and border, or an edge's stroke width
ele.height(): number | undefined

Read the first element's height in model pixels: a node's content height, excluding padding and border, or an edge's stroke width. A compound parent's height is derived from its children. The read reflects the current value during size animations.

Returns number | undefined

the height, or undefined when empty or removed

Example

console.log(eles.height()); // 30

Example graph and handle setup

#ele.padding()

// Node padding
ele.padding(): number | undefined

Node padding. Leaves have no padding (no compound-free padding prop); parents answer the resolved auto-bounds padding.

Returns number | undefined

the resolved padding in model px — 0 for leaves and for any graph with no compounds at all, the derived value for a parent; undefined when the collection is empty

Example

console.log(eles.padding()); // 0

Example graph and handle setup

#ele.paddedWidth()

// The drawn box: core dims + 2 x padding
ele.paddedWidth(): number | undefined

The drawn box: core dims + 2 x padding.

Returns number | undefined

the padded width — identical to width() for leaves, which have no padding; undefined when empty or removed

Example

console.log(eles.paddedWidth()); // 30

Example graph and handle setup

#ele.paddedHeight()

// The drawn box height: content height plus twice the padding
ele.paddedHeight(): number | undefined

The drawn box height: content height plus twice the padding. Identical to height() for leaves, which have no padding.

Returns number | undefined

the padded height, or undefined when empty or removed

Example

console.log(eles.paddedHeight()); // 30

Example graph and handle setup

#ele.outerWidth()

// The full drawn width including the border — padded width plus the border width
ele.outerWidth(): number | undefined

The full drawn width including the border — padded width plus the border width. This is the box bounds and endpoint clipping use.

Returns number | undefined

the outer width, or undefined when empty or removed

Example

console.log(eles.outerWidth()); // 30

Example graph and handle setup

#ele.outerHeight()

// The full drawn height including the border
ele.outerHeight(): number | undefined

The full drawn height including the border.

Returns number | undefined

the outer height, or undefined when empty or removed

Example

console.log(eles.outerHeight()); // 30

Example graph and handle setup

#eles.boundingBox(options?)

// The model-space box enclosing every element of the collection
eles.boundingBox(options?: { includeLabels?: boolean }): { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

The model-space box enclosing every element of the collection.

Labels are included by default. Node label terms are exact (the laid text block at its anchor plus text-box padding); edge label terms are conservative (a rotation-safe radius about both endpoints), so a box may be slightly larger than the ink but never smaller. The box also covers ghost offsets, overlay/underlay padding and outlines.

Parameters
NameDescription
options: { includeLabels?: boolean }?

{ includeLabels } (default true)

Fields of options
NameDescription
includeLabels: boolean?
Returns { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

{ x1, y1, x2, y2, w, h } in model coordinates

Example

console.log(cy.nodes().boundingBox().w); // 130

Example graph and handle setup

Throws

on an unknown option key — a typo must not silently change fit semantics

See

Collection#labelBoundingBox for the label box alone

#eles.labelBoundingBox()

// The exact laid label boxes of this collection's elements, unioned: node labels at their anchors, edge mid-labels at the drawn midpoint, end labels conservatively about their endpoint
eles.labelBoundingBox(): { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

The exact laid label boxes of this collection's elements, unioned: node labels at their anchors, edge mid-labels at the drawn midpoint, end labels conservatively about their endpoint. Empty (zero) when nothing is labelled. Headless dims are estimates (recorded).

Returns { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

Example

console.log(cy.nodes().labelBoundingBox().w); // 0

Example graph and handle setup

#eles.renderedBoundingBox(options?)

// boundingBox() transformed into rendered (on-screen) coordinates
eles.renderedBoundingBox(options?: { includeLabels?: boolean }): { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

boundingBox() transformed into rendered (on-screen) coordinates.

Parameters
NameDescription
options: { includeLabels?: boolean }?

as boundingBox(): { includeLabels }, default true; an unknown key throws

Fields of options
NameDescription
includeLabels: boolean?
Returns { x1: number; y1: number; x2: number; y2: number; w: number; h: number; }

the rendered-space box

Example

cy.zoom(1); cy.pan({ x: 0, y: 0 });
console.log(cy.nodes().renderedBoundingBox().w); // 130

Example graph and handle setup

Also spelled eles.renderedBoundingbox.

#ele.renderedWidth()

// width() scaled by the current zoom — the on-screen width in CSS px
ele.renderedWidth(): number | undefined

width() scaled by the current zoom — the on-screen width in CSS px.

Returns number | undefined

the rendered width, or undefined when empty or removed

Example

cy.zoom(2);
console.log(cy.getElementById('a').renderedWidth()); // 60

Example graph and handle setup

#ele.renderedHeight()

// height() scaled by the current zoom
ele.renderedHeight(): number | undefined

height() scaled by the current zoom.

Returns number | undefined

the rendered height, or undefined when empty or removed

Example

cy.zoom(2);
console.log(cy.getElementById('a').renderedHeight()); // 60

Example graph and handle setup

#ele.renderedOuterWidth()

// outerWidth() scaled by the current zoom
ele.renderedOuterWidth(): number | undefined

outerWidth() scaled by the current zoom.

Returns number | undefined

the rendered outer width, or undefined when empty or removed

Example

cy.zoom(2);
console.log(cy.getElementById('a').renderedOuterWidth()); // 60

Example graph and handle setup

#ele.renderedOuterHeight()

// outerHeight() scaled by the current zoom
ele.renderedOuterHeight(): number | undefined

outerHeight() scaled by the current zoom.

Returns number | undefined

the rendered outer height, or undefined when empty or removed

Example

cy.zoom(2);
console.log(cy.getElementById('a').renderedOuterHeight()); // 60

Example graph and handle setup

All guides · Alphabetical API index · Read continuously