Skip to content

Viewport manipulation

Read and change the view without changing model positions.

#Pan, zoom, fit and bounds

The viewport is a zoom factor and pan offset. Programmatic pan()/zoom() respect the corresponding enabled flags, and user-gesture gates are separate controls. fit(), center(), and the extent readers use the renderer/model bounds contract rather than changing element positions.

#cy.zoom()

// Get the zoom level
cy.zoom(): number

Read the current zoom level.

Returns number

the current zoom level as a number

Example

cy.zoom(1);
console.log(cy.zoom()); // 1

Example graph and handle setup

#cy.zoom(level)

// Set the zoom level
cy.zoom(level: number): this

Set the zoom level, clamped to zoomRange(). Does nothing when zoomingEnabled() is false. A changed viewport emits a zoom event and a viewport event.

Parameters
NameDescription
level: number

the new zoom level

Returns this

this core, for chaining

Example

const result = cy.zoom(2);
console.log(result === cy); // true

Example graph and handle setup

#cy.zoom(options)

// Zoom about a position
cy.zoom(options: ZoomOptions): this

Zoom about a fixed model or rendered position. Does nothing when zoomingEnabled() is false. A changed viewport emits a zoom event and a viewport event.

Parameters
NameDescription
options: ZoomOptions

the level and the position to keep fixed

Fields of options
NameDescription
level: number

New zoom level, clamped to the graph's zoomRange().

position: Position?

model point to keep fixed while zooming

renderedPosition: Position?

rendered (on-screen) point to keep fixed while zooming

Returns this

this core, for chaining

Example

cy.zoom({ level: 2, renderedPosition: { x: 0, y: 0 } });
console.log(cy.zoom()); // 2

Example graph and handle setup

#cy.pan()

// Get the pan position
cy.pan(): Position

Read the current pan offset in rendered CSS pixels.

Returns Position

the rendered-space offset

Example

cy.pan({ x: 40, y: 20 });
console.log(cy.pan()); // { x: 40, y: 20 }

Example graph and handle setup

#cy.pan(pan)

// Set the pan position
cy.pan(pan: Position): this

// Set the pan position
cy.pan(pan: Position | undefined): Position | this

Set the pan offset. A no-op while panningEnabled() is false.

Parameters
NameDescription
pan: Position

the new rendered-space offset

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

this core, for chaining

Example

const result = cy.pan({ x: 40, y: 20 });
console.log(result === cy); // true

Example graph and handle setup

Get the pan offset, or set it. Setting is a no-op while panningEnabled() is false.

Parameters
NameDescription
pan: Position | undefined

the new rendered-space offset; omit to read

Fields of pan
NameDescription
x: number
y: number
Returns Position | this

the current pan when reading, this core when setting

Example

cy.pan({ x: 40, y: 20 });
console.log(cy.pan()); // { x: 40, y: 20 }

Example graph and handle setup

#cy.panBy(delta)

// Shift the pan by a delta
cy.panBy(delta: Position): this

Shift the pan by a delta. A no-op while panningEnabled() is false.

Parameters
NameDescription
delta: Position

the rendered-space offset to add

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

this core, for chaining

Example

cy.pan({ x: 0, y: 0 });
cy.panBy({ x: 10, y: 5 });
console.log(cy.pan()); // { x: 10, y: 5 }

Example graph and handle setup

#cy.fit(eles?, padding?)

// Pan and zoom so the given elements fill the viewport
cy.fit(eles?: Collection, padding?: number): this

Pan and zoom so the given elements fill the viewport.

Bounds include labels by default, so a fit never clips the text it was asked to show; edge-label terms are conservative, so a fit may slightly over-fit but never under-fits.

Parameters
NameDescription
eles: Collection?

the elements to fit; omit for the whole graph

padding: number?Default: 0

rendered-space padding around the box

Returns this

this core, for chaining

Example

cy.fit(cy.nodes(), 20);
console.log(cy.zoom() > 0); // true

Example graph and handle setup

#cy.center(eles?)

// Pan so the given elements are centred, leaving the zoom alone
cy.center(eles?: Collection): this

Pan so the given elements are centred, leaving the zoom alone. Bounds include labels, as in fit().

Parameters
NameDescription
eles: Collection?

the elements to centre on; omit for the whole graph

Returns this

this core, for chaining

Example

cy.center(cy.nodes());
console.log(Number.isFinite(cy.pan().x)); // true

Example graph and handle setup

Also spelled cy.centre.

#cy.extent()

// The model-space rectangle currently visible, as { x1, y1, x2, y2, w, h } — the inverse of the pan/zoom transform applied to the viewport box
cy.extent(): Extent

The model-space rectangle currently visible, as { x1, y1, x2, y2, w, h } — the inverse of the pan/zoom transform applied to the viewport box.

Returns Extent

the visible extent in model coordinates

Example

cy.zoom(1); cy.pan({ x: 0, y: 0 });
console.log(cy.extent().w); // 800

Example graph and handle setup

#cy.renderedExtent()

// The rendered (on-screen) viewport rectangle
cy.renderedExtent(): Extent

The rendered (on-screen) viewport rectangle.

Returns Extent

the container's box in rendered px, anchored at the origin — the rendered-space counterpart of extent(), which is the same box projected into model coordinates

Example

console.log(cy.renderedExtent().w); // 800

Example graph and handle setup

See

Core#extent for the model-coordinate form

#cy.size()

// Rendered dimensions as { width, height }
cy.size(): { width: number; height: number }

Rendered dimensions as { width, height }.

Returns { width: number; height: number }

Example

console.log(cy.size()); // { width: 800, height: 600 }

Example graph and handle setup

#cy.minZoom()

// Get the minimum zoom, or set it
cy.minZoom(): number

Get the minimum zoom, or set it. Setting re-clamps the current zoom.

Returns number

the current minZoom value

Example

console.log(cy.minZoom()); // 1e-50

Example graph and handle setup

#cy.minZoom(zoom)

// Get the minimum zoom, or set it
cy.minZoom(zoom: number): this

Get the minimum zoom, or set it. Setting re-clamps the current zoom.

Parameters
NameDescription
zoom: number

the new minimum

Returns this

this core, for chaining

Example

const result = cy.minZoom(1e-50);
console.log(result === cy); // true

Example graph and handle setup

#cy.maxZoom()

// Get the maximum zoom, or set it
cy.maxZoom(): number

Get the maximum zoom, or set it. Setting re-clamps the current zoom.

Returns number

the current maxZoom value

Example

console.log(cy.maxZoom()); // 1e+50

Example graph and handle setup

#cy.maxZoom(zoom)

// Get the maximum zoom, or set it
cy.maxZoom(zoom: number): this

Get the maximum zoom, or set it. Setting re-clamps the current zoom.

Parameters
NameDescription
zoom: number

the new maximum

Returns this

this core, for chaining

Example

const result = cy.maxZoom(1e+50);
console.log(result === cy); // true

Example graph and handle setup

#cy.zoomRange(min, max?)

// Set both zoom bounds; accepts (min, max) or { min, max }
cy.zoomRange(min: number | { min?: number; max?: number }, max?: number): this

Set both zoom bounds; accepts (min, max) or { min, max }.

Parameters
NameDescription
min: number | { min?: number; max?: number }

the minimum zoom, or an object carrying both bounds

max: number?

the maximum zoom, when min is a number

Fields of min
NameDescription
min: number?
max: number?
Returns this

this core, for chaining

Example

cy.zoomRange(0.5, 4);
console.log([cy.minZoom(), cy.maxZoom()]); // [0.5, 4]

Example graph and handle setup

#cy.viewport(opts)

// Set zoom and/or pan together, emitting once
cy.viewport(opts: { zoom?: number; pan?: Position }): this

Set zoom and/or pan together, emitting once.

Parameters
NameDescription
opts: { zoom?: number; pan?: Position }

the zoom and/or pan to apply; omitted keys are left as they are

Fields of opts
NameDescription
zoom: number?
pan: Position?
Returns this

this core, for chaining

Example

cy.viewport({ zoom: 2, pan: { x: 40, y: 20 } });
console.log(cy.zoom()); // 2

Example graph and handle setup

#cy.reset()

// Reset the viewport to zoom 1, pan (0, 0)
cy.reset(): this

Reset the viewport to zoom 1, pan (0, 0).

Returns this

Example

cy.pan({ x: 40, y: 20 });
cy.zoom(2);
cy.reset();
cy.zoom(1);
console.log(cy.zoom()); // 1

Example graph and handle setup

#cy.resize()

// Re-measure the container, redraw and emit 'resize' (the redraw is a no-op when headless; the event still fires)
cy.resize(): this

Re-measure the container, redraw and emit a resize event (the redraw is a no-op when headless; the event still fires).

Rarely needed: a ResizeObserver on the container re-measures on every size change and emits a resize event itself — once per change, and not again for a change this call already applied — so container size changes are handled automatically. Call it where no observer exists or none can see the change.

Returns this

this core

Example

// After the graph container changes size, refresh viewport dimensions.
cy.resize();
console.log(cy.width() > 0); // true

Example graph and handle setup

Also spelled cy.invalidateSize.

#cy.width()

// The rendered width in CSS px
cy.width(): number

The rendered width in CSS px. Headless instances report the configured headlessWidth (default 800), so viewport maths works without a DOM.

Returns number

the viewport width in CSS px

Example

console.log(cy.width()); // 800

Example graph and handle setup

#cy.height()

// The rendered height in CSS px
cy.height(): number

The rendered height in CSS px. Headless instances report the configured headlessHeight (default 600).

Returns number

the viewport height in CSS px

Example

console.log(cy.height()); // 600

Example graph and handle setup

#Picking and visible counts

#cy.pick(x, y)

// Async GPU pick at a rendered (CSS px) position; resolves with the element under the point or null (always null when headless — the sync, node-only cy.nodeAt() computes headless)
cy.pick(x: number, y: number): Promise<Collection<NodeData, EdgeData> | null>

Async GPU pick at a rendered (CSS px) position; resolves with the element under the point or null (always null when headless — the sync, node-only cy.nodeAt() computes headless).

Exact: a hit is a point on the drawn element. The pointer gestures additionally apply hit halos (8 rendered px around edges for a mouse, 24 for touch; 2/8 around nodes), so a press can land where this method answers null; the halo belongs to the gesture, not the API.

What wins when elements overlap, as contract: a non-parent node, then an edge, then a compound parent — the reverse of the drawing order in (parents, edges, leaves), so the answer is always the topmost thing drawn at that point. Nesting depth does not change it: a parent inside another parent still draws under every edge, and among parents the deepest wins. Drawing order is structural; there are no z-index or z-compound-depth properties.

Parameters
NameDescription
x: number

rendered (CSS px) x, relative to the container

y: number

rendered (CSS px) y

Returns Promise<Collection<NodeData, EdgeData> | null>

the element under the point, or null

Example

// Exact GPU picking returns null on a headless core.
console.log(await cy.pick(100, 100)); // null

Example graph and handle setup

#cy.nodeAt(x, y)

// Find the topmost node at a rendered position, measured in CSS pixels from the container's top-left corner
cy.nodeAt(x: number, y: number): Collection<NodeData, EdgeData, NodeData> | null

Find the topmost node at a rendered position, measured in CSS pixels from the container's top-left corner. Returns null when no node is hit. Use pick() to test both nodes and edges asynchronously.

Node visibility and level of detail affect the result. In a headless core, the calculation uses the viewport and default rendering thresholds at a device-pixel ratio of 1.

Parameters
NameDescription
x: number

rendered (CSS px) x, relative to the container

y: number

rendered (CSS px) y

Returns Collection<NodeData, EdgeData, NodeData> | null

the node under the point, or null (background, an edge only, or a destroyed instance)

Example

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

Example graph and handle setup

Also spelled cy.pickNode.

See

Core#pick for edges and the full draw-order answer

#cy.viewportCounts()

// Count visible nodes and edges at each level of detail in the current viewport
cy.viewportCounts(): Promise<ViewportCounts | null>

Count visible nodes and edges at each level of detail in the current viewport. Resolves after the renderer computes the counts for a frame. Resolves null when headless, destroyed, or when the device is lost before that frame completes.

For synchronous geometric containment, use elementsInBox() with the bounds returned by extent(). That query includes elements regardless of whether they are large enough to draw.

Returns Promise<ViewportCounts | null>

{ nodes, edges } for the next frame drawn, or null

Example

// A headless core has no rendered frame to count.
console.log(await cy.viewportCounts()); // null

Example graph and handle setup

All guides · Alphabetical API index · Read continuously