Skip to content

Events

Understand ownership, bubbling, vocabulary and event objects.

#Ownership, delegation and bubbling

Core and element event methods use literal, space-separated event names. cy.on() and cy.one() bind to the core; with three arguments they delegate to elements using a predicate over the event target. eles.on() and eles.one() bind per element in the collection. Core removeAllListeners() clears core, element-bound and delegated listeners. Collection off(events, handler?) removes named event types from its elements; there is no collection-wide remove-every-type method. Keep your handler references so that you can remove the listeners your application installs.

const isNode = ele => ele.isNode();
const onNodeTap = event => {
const node = event.target;
console.log(node.id());
};
cy.on('tap', isNode, onNodeTap);
// Later, pass the same predicate and handler function objects.
cy.off('tap', isNode, onNodeTap);

Predicates compare by function identity when removing a delegated listener. Create the predicate once if it needs to be removed later. Collection event handlers are qualified to their element and continue to work when the store compacts slots, because the listener follows element identity rather than a slot number.

Events from an element bubble through its compound ancestors and then to the core. stopPropagation() stops later graph event phases and calls the underlying DOM event's stopPropagation() when available. Returning false from a handler has the same graph bubbling effect. preventDefault() only prevents the browser's default via originalEvent; it does not veto selection, grabbing or other Cytoscape gesture defaults. Use the dedicated options such as autounselectify, autoungrabify, boxSelectionEnabled, userPanningEnabled or userZoomingEnabled to control those interactions.

#Event vocabulary

Event names are literal strings. The built-in interaction vocabulary includes these families:

  • Normalized press events: tapstart, tapdrag, tapend, tap, taphold, dbltap, tapselect, and tapunselect.
  • Drag state: grab, grabon, drag, free, freeon, dragfree, and dragfreeon. The -on forms target the directly grabbed element; the plain forms also reach selected companions moved with it.
  • Drag-hover and context interaction: tapdragover/tapdragout, cxttapstart, cxtdrag, cxttapend, cxttap, and cxtdragover/cxtdragout.
  • Pointer input: pointerdown, pointermove, pointerup, pointercancel, pointerover, and pointerout.
  • Viewport gestures: dragpan, scrollzoom, pinchzoom, and scrollpan. They are core events and carry model/rendered positions where available.
  • Selection and box selection: select, unselect, boxstart, box, boxend, and boxselect.
  • Viewport/model notifications: pan, zoom, viewport, and position.

Other emitted core events include element/data changes (add, remove, data, patch), style and batch changes (style, legendchange, batchstart, batchend), layout lifecycle (layoutstart, layoutready, layoutstop), progressive loading (loadstart, loadchunk, loadready, loadstop), resize/render, device lifecycle and errors, and destroy. Their payloads are described by the corresponding API entries.

The tapdragover/tapdragout and cxtdragover/cxtdragout pairs target nodes only. They use synchronous CPU node picking; they do not promise edge hover targets. Gesture hit-testing also applies the interaction halo used for easier edge and node targeting, while cy.pick() remains exact geometry. See the pick methods in the API reference when a query must match geometric API behavior instead of pointer behavior.

The raw mouse/touch re-emits and vmouse* aliases are not emitted; pointer* is the raw-input family. The older mouseover and mouseout names remain available too. The library accepts arbitrary custom names, so it does not reject a misspelling or a name that no implementation emits. Such a listener registers but never fires unless application code emits that exact name.

Namespaces are not parsed: 'tap.ns' is one literal type, not a tap listener with namespace metadata. emit('tap') does not reach a 'tap.ns' handler, while emit('tap.ns') reaches that exact name. The same rule governs off().

#Event object

#Event payload and state

Event exposes type, target, cy, timestamp, optional model and rendered positions, the original DOM event when one exists, and lifecycle payloads such as layout, cancelled, progress and diff when appropriate. Element event targets are one-element collections; core events target the core. The layout property identifies the layout instance for lifecycle events. Pointer positions are translated between model and rendered spaces using the current viewport.

#event.type

// the event type, e.g
event.type: string

the event type, e.g. 'tap' — never namespaced

Returns string

Example

console.log(event.type); // "example"

Example graph and handle setup

#event.cy

// the core the event was raised on
event.cy: Core<NodeData, EdgeData>

the core the event was raised on

Returns Core<NodeData, EdgeData>

Example

console.log(event.cy === cy); // true

Example graph and handle setup

#event.renderedPosition

// Get the position
event.renderedPosition: Position

rendered-space position; derived from position and the viewport

Returns Position

Example

console.log(event.renderedPosition); // undefined

Example graph and handle setup

#event.originalEvent

// the DOM event behind a gesture, when there was one
event.originalEvent: NativeEvent

the DOM event behind a gesture, when there was one

Returns NativeEvent

Example

console.log(event.originalEvent); // undefined

Example graph and handle setup

#event.layout

// the layout instance, on the layout lifecycle events
event.layout: unknown

the layout instance, on the layout lifecycle events

Returns unknown

Example

console.log(event.layout); // undefined

Example graph and handle setup

#event.cancelled

// on layoutstop, whether the run was cancelled; on loadstop, whether the load was
event.cancelled: boolean

on layoutstop, whether the run was cancelled; on loadstop, whether the load was

Returns boolean

Example

console.log(event.cancelled); // undefined

Example graph and handle setup

#event.diff

// on patch, what the patch added, removed and updated
event.diff: PatchDiff<NodeData, EdgeData>

on patch, what the patch added, removed and updated

Returns PatchDiff<NodeData, EdgeData>

Example

console.log(event.diff); // undefined

Example graph and handle setup

#event.timeStamp

// when the event was built, Date.now() unless the caller supplied one
event.timeStamp: number

when the event was built, Date.now() unless the caller supplied one

Returns number

Example

console.log(Number.isFinite(event.timeStamp)); // true

Example graph and handle setup

#event.isDefaultPrevented()

// Whether preventDefault() was called on this event
event.isDefaultPrevented(): boolean

Whether preventDefault() was called on this event. This flag concerns the browser's default behaviour, such as page scrolling. Use the core's interaction controls to disable graph selection, dragging or box selection.

Returns boolean

Example

console.log(event.isDefaultPrevented()); // false

Example graph and handle setup

#event.isPropagationStopped()

// Whether stopPropagation() has been called — read by the compound bubbling walk, where it halts the phase sequence
event.isPropagationStopped(): boolean

Whether stopPropagation() has been called — read by the compound bubbling walk, where it halts the phase sequence.

Returns boolean

Example

console.log(event.isPropagationStopped()); // false

Example graph and handle setup

#Browser defaults and exact picking

The interaction vocabulary deliberately separates graph events from browser defaults. Pointer-derived gestures include hit tolerance and device-specific semantics; the exact geometric cy.pick() API does not apply the gesture halo. See the API reference for its contract and the core options for independent gesture controls.

#event.preventDefault()

// Prevent the original browser event's default behaviour when one is attached, for example page scrolling
event.preventDefault(): void

Prevent the original browser event's default behaviour when one is attached, for example page scrolling. This does not disable graph selection or dragging; use core controls such as autounselectify(), autoungrabify() and boxSelectionEnabled() for graph gestures.

Returns void

Example

event.preventDefault();
console.log(event.isDefaultPrevented()); // true

Example graph and handle setup

#event.stopPropagation()

// Stop the event bubbling to further phases: the remaining ancestors and the core do not see it
event.stopPropagation(): void

Stop the event bubbling to further phases: the remaining ancestors and the core do not see it. Returning false from a handler does the same. With originalEvent attached this also calls the DOM event's stopPropagation(), so an outer DOM listener stops seeing it too.

Returns void

Example

event.stopPropagation();
console.log(event.isPropagationStopped()); // true

Example graph and handle setup

All guides · Alphabetical API index · Read continuously