Skip to content

Interaction controls

Control programmatic operations, user gestures and interaction defaults.

#cy.autolock()

// Read whether every node is locked (immovable) regardless of its own locked flag — the graph-wide override
cy.autolock(): boolean

Read whether every node is locked (immovable) regardless of its own locked flag — the graph-wide override. Turned on mid-tween, every running position tween holds where it got to, as a node locked mid-tween does.

Returns boolean

the current autolock value

Example

console.log(cy.autolock()); // false

Example graph and handle setup

#cy.autolock(bool)

// Set whether every node is locked (immovable) regardless of its own locked flag — the graph-wide override
cy.autolock(bool: boolean): this

Set whether every node is locked (immovable) regardless of its own locked flag — the graph-wide override. Turned on mid-tween, every running position tween holds where it got to, as a node locked mid-tween does.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

const result = cy.autolock(false);
console.log(result === cy); // true

Example graph and handle setup

Also spelled cy.autolockNodes.

#cy.autoungrabify()

// Read whether every node is ungrabbable regardless of its own grabbable flag
cy.autoungrabify(): boolean

Read whether every node is ungrabbable regardless of its own grabbable flag. Unlike autolock(), this blocks only user dragging; programmatic position writes still apply.

Returns boolean

the current autoungrabify value

Example

console.log(cy.autoungrabify()); // false

Example graph and handle setup

#cy.autoungrabify(bool)

// Set whether every node is ungrabbable regardless of its own grabbable flag
cy.autoungrabify(bool: boolean): this

Set whether every node is ungrabbable regardless of its own grabbable flag. Unlike autolock(), this blocks only user dragging; programmatic position writes still apply.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

const result = cy.autoungrabify(false);
console.log(result === cy); // true

Example graph and handle setup

Also spelled cy.autoungrabifyNodes.

#cy.autounselectify()

// Read whether every element is unselectable regardless of its own selectable flag
cy.autounselectify(): boolean

Read whether every element is unselectable regardless of its own selectable flag. Programmatic select() still applies.

Returns boolean

the current autounselectify value

Example

console.log(cy.autounselectify()); // false

Example graph and handle setup

#cy.autounselectify(bool)

// Set whether every element is unselectable regardless of its own selectable flag
cy.autounselectify(bool: boolean): this

Set whether every element is unselectable regardless of its own selectable flag. Programmatic select() still applies.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

const result = cy.autounselectify(false);
console.log(result === cy); // true

Example graph and handle setup

#cy.panningEnabled()

// Check whether panning is enabled
cy.panningEnabled(): boolean

Read whether panning is allowed at all — programmatic pan() included. Use userPanningEnabled() to block only the gesture.

Returns boolean

the current panningEnabled value

Example

console.log(cy.panningEnabled()); // true

Example graph and handle setup

#cy.panningEnabled(bool)

// Enable or disable panning
cy.panningEnabled(bool: boolean): this

Set whether panning is allowed at all — programmatic pan() included. Use userPanningEnabled() to block only the gesture.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.userPanningEnabled()

// Check whether user panning is enabled
cy.userPanningEnabled(): boolean

Read whether the user may pan by dragging. Programmatic pan() is unaffected.

Returns boolean

the current userPanningEnabled value

Example

console.log(cy.userPanningEnabled()); // true

Example graph and handle setup

#cy.userPanningEnabled(bool)

// Enable or disable user panning
cy.userPanningEnabled(bool: boolean): this

Set whether the user may pan by dragging. Programmatic pan() is unaffected.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.zoomingEnabled()

// Check whether zooming is enabled
cy.zoomingEnabled(): boolean

Read whether zooming is allowed at all — programmatic zoom() included. Use userZoomingEnabled() to block only the gesture.

Returns boolean

the current zoomingEnabled value

Example

console.log(cy.zoomingEnabled()); // true

Example graph and handle setup

#cy.zoomingEnabled(bool)

// Enable or disable zooming
cy.zoomingEnabled(bool: boolean): this

Set whether zooming is allowed at all — programmatic zoom() included. Use userZoomingEnabled() to block only the gesture.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.userZoomingEnabled()

// Check whether user zooming is enabled
cy.userZoomingEnabled(): boolean

Read whether the user may zoom by wheel or pinch. Programmatic zoom() is unaffected.

Returns boolean

the current userZoomingEnabled value

Example

console.log(cy.userZoomingEnabled()); // true

Example graph and handle setup

#cy.userZoomingEnabled(bool)

// Enable or disable user zooming
cy.userZoomingEnabled(bool: boolean): this

Set whether the user may zoom by wheel or pinch. Programmatic zoom() is unaffected.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.boxSelectionIncludesLabels()

// Check whether box selection includes labels
cy.boxSelectionIncludesLabels(): boolean

Whether box selection considers label boxes as well as node bodies (default off). Its sense follows boxSelectionMode: under 'contain' the label box must also be inside the band, under 'overlap' a label that merely crosses the band is enough.

Returns boolean

the current boxSelectionIncludesLabels value

Example

console.log(cy.boxSelectionIncludesLabels()); // false

Example graph and handle setup

#cy.boxSelectionIncludesLabels(bool)

// Include or exclude labels in box selection
cy.boxSelectionIncludesLabels(bool: boolean): this

Whether box selection considers label boxes as well as node bodies (default off). Its sense follows boxSelectionMode: under 'contain' the label box must also be inside the band, under 'overlap' a label that merely crosses the band is enough.

Parameters
NameDescription
bool: boolean

the setting to apply

Returns this

this core, for chaining

Example

const result = cy.boxSelectionIncludesLabels(false);
console.log(result === cy); // true

Example graph and handle setup

#cy.boxSelectionMode()

// What the box-selection gesture counts as caught: 'contain' (default) selects only elements wholly inside the band; 'overlap' selects anything the band touches — a node whose box intersects it, an edge any part of whose drawn path crosses it.
cy.boxSelectionMode(): BoxSelectionMode

What the box-selection gesture counts as caught: 'contain' (default) selects only elements wholly inside the band; 'overlap' selects anything the band touches — a node whose box intersects it, an edge any part of whose drawn path crosses it..

Two notes on the boundary. This setting is read by the gesture only: cy.elementsInBox() stays the pure geometric containment query it has always been, so a programmatic caller's results do not change under this setting. And boxSelectionIncludesLabels reverses sense with the mode, because it can only mean one thing in each: under 'contain' the label box must also be inside, under 'overlap' a label that crosses the band is enough.

Returns BoxSelectionMode

the current boxSelectionMode value

Example

console.log(cy.boxSelectionMode()); // "contain"

Example graph and handle setup

#cy.boxSelectionMode(mode)

// What the box-selection gesture counts as caught: 'contain' (default) selects only elements wholly inside the band; 'overlap' selects anything the band touches — a node whose box intersects it, an edge any part of whose drawn path crosses it.
cy.boxSelectionMode(mode: BoxSelectionMode): this

What the box-selection gesture counts as caught: 'contain' (default) selects only elements wholly inside the band; 'overlap' selects anything the band touches — a node whose box intersects it, an edge any part of whose drawn path crosses it..

Two notes on the boundary. This setting is read by the gesture only: cy.elementsInBox() stays the pure geometric containment query it has always been, so a programmatic caller's results do not change under this setting. And boxSelectionIncludesLabels reverses sense with the mode, because it can only mean one thing in each: under 'contain' the label box must also be inside, under 'overlap' a label that crosses the band is enough.

Parameters
NameDescription
mode: BoxSelectionMode

the new mode

Returns this

this core, for chaining

Example

const result = cy.boxSelectionMode("contain");
console.log(result === cy); // true

Example graph and handle setup

Throws

if mode is neither 'contain' nor 'overlap'

#cy.boxSelectionEnabled()

// Check whether box selection is enabled
cy.boxSelectionEnabled(): boolean

Read whether the box-selection gesture is available.

Returns boolean

the current boxSelectionEnabled value

Example

console.log(cy.boxSelectionEnabled()); // true

Example graph and handle setup

#cy.boxSelectionEnabled(bool)

// Enable or disable box selection
cy.boxSelectionEnabled(bool: boolean): this

Set whether the box-selection gesture is available.

Parameters
NameDescription
bool: boolean

the new setting

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.pointerCursors()

// Get cursor settings
cy.pointerCursors(): boolean | Partial<CursorMap>

Read the pointer cursor settings.

Returns boolean | Partial<CursorMap>

true or false for built-in cursors, or the custom cursor configuration

Example

console.log(cy.pointerCursors()); // true

Example graph and handle setup

#cy.pointerCursors(cursors)

// Set cursor settings
cy.pointerCursors(cursors: boolean | Partial<CursorMap>): this

Set the pointer cursors used by gestures.

Parameters
NameDescription
cursors: boolean | Partial<CursorMap>

true for built-in cursors, false to disable, or custom cursors

Returns this

this core, for chaining

Example

const result = cy.pointerCursors(false);
console.log(result === cy); // true

Example graph and handle setup

#cy.selectionType()

// How user selection composes: 'single' (a tap or box replaces the selection) or 'additive' (taps toggle and boxes add, as if a multiple-select key were always held)
cy.selectionType(): 'single' | 'additive'

How user selection composes: 'single' (a tap or box replaces the selection) or 'additive' (taps toggle and boxes add, as if a multiple-select key were always held).

Returns 'single' | 'additive'

the current selectionType value

Example

console.log(cy.selectionType()); // "single"

Example graph and handle setup

Throws

if type is neither 'single' nor 'additive'

#cy.selectionType(type)

// How user selection composes: 'single' (a tap or box replaces the selection) or 'additive' (taps toggle and boxes add, as if a multiple-select key were always held)
cy.selectionType(type: 'single' | 'additive'): this

How user selection composes: 'single' (a tap or box replaces the selection) or 'additive' (taps toggle and boxes add, as if a multiple-select key were always held).

Parameters
NameDescription
type: 'single' | 'additive'

the new mode

Returns this

this core, for chaining

Example

const result = cy.selectionType("single");
console.log(result === cy); // true

Example graph and handle setup

Throws

if type is neither 'single' nor 'additive'

#cy.multiClickDebounceTime()

// The dbltap/onetap debounce window in ms (default 250)
cy.multiClickDebounceTime(): number

The dbltap/onetap debounce window in ms (default 250).

Returns number

the current multiClickDebounceTime value

Example

console.log(cy.multiClickDebounceTime()); // 250

Example graph and handle setup

#cy.multiClickDebounceTime(ms)

// The dbltap/onetap debounce window in ms (default 250)
cy.multiClickDebounceTime(ms: number): this

The dbltap/onetap debounce window in ms (default 250).

Parameters
NameDescription
ms: number

the window to set

Returns this

this core, for chaining

Example

const result = cy.multiClickDebounceTime(250);
console.log(result === cy); // true

Example graph and handle setup

Throws

if ms is not a finite non-negative number

#cy.wheelSensitivity()

// Wheel-zoom sensitivity: a multiplier on the zoom-per-wheel-tick exponent (default 1)
cy.wheelSensitivity(): number

Wheel-zoom sensitivity: a multiplier on the zoom-per-wheel-tick exponent (default 1). Non-default values warn once per instance — a custom sensitivity tuned on one mouse/OS zooms unnaturally on others.

Returns number

the current wheelSensitivity value

Example

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

Example graph and handle setup

#cy.wheelSensitivity(mult)

// Wheel-zoom sensitivity: a multiplier on the zoom-per-wheel-tick exponent (default 1)
cy.wheelSensitivity(mult: number): this

Wheel-zoom sensitivity: a multiplier on the zoom-per-wheel-tick exponent (default 1). Non-default values warn once per instance — a custom sensitivity tuned on one mouse/OS zooms unnaturally on others.

Parameters
NameDescription
mult: number

the multiplier to set

Returns this

this core, for chaining

Example

const result = cy.wheelSensitivity(1);
console.log(result === cy); // true

Example graph and handle setup

Throws

if mult is not a finite positive number (0 would freeze the zoom, so the bound is strict where the threshold setters allow 0)

#cy.wheelBehavior()

// What a wheel over the canvas does: 'zoom' (the default) zooms about the cursor; 'pan' pans by the wheel's delta and emits scrollpan, while a ctrl- or meta-wheel — the encoding a trackpad pinch arrives in — still zooms; 'modifier-zoom' leaves the plain wheel to the page (it scrolls past the graph) and zooms only on a ctrl- or meta-wheel
cy.wheelBehavior(): WheelBehavior

What a wheel over the canvas does: 'zoom' (the default) zooms about the cursor; 'pan' pans by the wheel's delta and emits a scrollpan event, while a ctrl- or meta-wheel — the encoding a trackpad pinch arrives in — still zooms; 'modifier-zoom' leaves the plain wheel to the page (it scrolls past the graph) and zooms only on a ctrl- or meta-wheel. Every mode honours the toggles (userZoomingEnabled gates a zoom, userPanningEnabled a pan), and a wheel the settings leave inert is not preventDefault()ed, so the page scrolls in every mode.

Returns WheelBehavior

the current wheelBehavior value

Example

console.log(cy.wheelBehavior()); // "zoom"

Example graph and handle setup

Throws

if mode is not 'zoom', 'pan' or 'modifier-zoom'

#cy.wheelBehavior(mode)

// What a wheel over the canvas does: 'zoom' (the default) zooms about the cursor; 'pan' pans by the wheel's delta and emits scrollpan, while a ctrl- or meta-wheel — the encoding a trackpad pinch arrives in — still zooms; 'modifier-zoom' leaves the plain wheel to the page (it scrolls past the graph) and zooms only on a ctrl- or meta-wheel
cy.wheelBehavior(mode: WheelBehavior): this

What a wheel over the canvas does: 'zoom' (the default) zooms about the cursor; 'pan' pans by the wheel's delta and emits a scrollpan event, while a ctrl- or meta-wheel — the encoding a trackpad pinch arrives in — still zooms; 'modifier-zoom' leaves the plain wheel to the page (it scrolls past the graph) and zooms only on a ctrl- or meta-wheel. Every mode honours the toggles (userZoomingEnabled gates a zoom, userPanningEnabled a pan), and a wheel the settings leave inert is not preventDefault()ed, so the page scrolls in every mode.

Parameters
NameDescription
mode: WheelBehavior

the behaviour to set

Returns this

this core, for chaining

Example

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

Example graph and handle setup

Throws

if mode is not 'zoom', 'pan' or 'modifier-zoom'

#cy.desktopTapThreshold()

// Css px a mouse/pen press may move and still count as a tap (default 4)
cy.desktopTapThreshold(): number

Css px a mouse/pen press may move and still count as a tap (default 4).

Returns number

the current desktopTapThreshold value

Example

console.log(cy.desktopTapThreshold()); // 4

Example graph and handle setup

#cy.desktopTapThreshold(px)

// Css px a mouse/pen press may move and still count as a tap (default 4)
cy.desktopTapThreshold(px: number): this

Css px a mouse/pen press may move and still count as a tap (default 4).

Parameters
NameDescription
px: number

the new threshold

Returns this

this core, for chaining

Example

const result = cy.desktopTapThreshold(4);
console.log(result === cy); // true

Example graph and handle setup

Throws

if px is not a finite non-negative number

#cy.touchTapThreshold()

// Css px a touch press may move and still count as a tap (default 8)
cy.touchTapThreshold(): number

Css px a touch press may move and still count as a tap (default 8).

Returns number

the current touchTapThreshold value

Example

console.log(cy.touchTapThreshold()); // 8

Example graph and handle setup

#cy.touchTapThreshold(px)

// Css px a touch press may move and still count as a tap (default 8)
cy.touchTapThreshold(px: number): this

Css px a touch press may move and still count as a tap (default 8).

Parameters
NameDescription
px: number

the new threshold

Returns this

this core, for chaining

Example

const result = cy.touchTapThreshold(8);
console.log(result === cy); // true

Example graph and handle setup

Throws

if px is not a finite non-negative number

#cy.tapholdDuration()

// Unmoved-press duration before 'taphold' fires, ms (default 500)
cy.tapholdDuration(): number

Unmoved-press duration before 'taphold' fires, ms (default 500).

Returns number

the current tapholdDuration value

Example

console.log(cy.tapholdDuration()); // 500

Example graph and handle setup

#cy.tapholdDuration(ms)

// Unmoved-press duration before 'taphold' fires, ms (default 500)
cy.tapholdDuration(ms: number): this

Unmoved-press duration before 'taphold' fires, ms (default 500).

Parameters
NameDescription
ms: number

the new duration

Returns this

this core, for chaining

Example

const result = cy.tapholdDuration(500);
console.log(result === cy); // true

Example graph and handle setup

Throws

if ms is not a finite non-negative number

All guides · Alphabetical API index · Read continuously