Skip to content

Events

Bind core listeners or delegate to elements using predicates.

#Core event methods

The core can listen, delegate by an element predicate, emit custom events and remove listeners. removeAllListeners() on the core also removes element-bound and delegated listeners. The event vocabulary and bubbling rules are described in events. Layout lifecycle events are raised on the core. Async algorithm runs and progressive loads also report their own events and can be cancelled through their returned handles.

#cy.on(events, callback)

// Bind a direct listener
cy.on(events: string, callback: EventHandler<NodeData, EdgeData>): this

Listen for core and bubbled element events: cy.on('tap', handler). For delegation, use cy.on('tap', ele => ele.isNode(), handler). Event names match literally; 'tap.ns' is different from 'tap'. Custom names are allowed and fire when your application emits them.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>

the event handler

Returns this

this core, for chaining

Example

const seen = [];
const handler = event => seen.push(event.type);
cy.on('example', handler);
cy.emit('example');
cy.off('example', handler);
console.log(seen); // ['example']

Example graph and handle setup

#cy.on(events, predicate, callback)

// Bind a delegated listener
cy.on(events: string, predicate: ElePredicate<NodeData, EdgeData>, callback: EventHandler<NodeData, EdgeData>): this

Listen for events on the core. Use cy.on('tap', handler) for core and bubbled element events. To delegate, use cy.on('tap', ele => ele.isNode(), handler).

Custom event names are accepted; a name the library never emits fires only when your application emits it. Event names match literally: 'tap.ns' is different from 'tap'. See the event reference for emitted names.

To remove a delegated listener, pass the same predicate and handler objects to off().

Parameters
NameDescription
events: string

one or more space-separated event names

predicate: ElePredicate<NodeData, EdgeData>

( ele) => boolean over the event target; only runs for element targets

callback: EventHandler<NodeData, EdgeData>

the handler

Returns this

this core, for chaining

Example

const seen = [];
const handler = event => seen.push(event.target.id());
cy.on('example', node => node.isNode(), handler);
cy.getElementById('a').emit('example');
console.log(seen); // ['a']

Example graph and handle setup

Also spelled cy.addListener.

See

Core#off — remove listeners using the same function objects

#cy.one(events, callback)

// Bind a direct listener
cy.one(events: string, callback: EventHandler<NodeData, EdgeData>): this

Like on(), but the handler runs at most once and then removes itself.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>

the handler, when delegating

Returns this

this core, for chaining

Example

let count = 0;
cy.one('example', () => count++);
cy.emit('example');
cy.emit('example');
console.log(count); // 1

Example graph and handle setup

#cy.one(events, predicate, callback)

// Bind a delegated listener
cy.one(events: string, predicate: ElePredicate<NodeData, EdgeData>, callback: EventHandler<NodeData, EdgeData>): this

Like on() with delegation, but the handler runs at most once.

Parameters
NameDescription
events: string

one or more space-separated event names

predicate: ElePredicate<NodeData, EdgeData>

( ele) => boolean over the event target

callback: EventHandler<NodeData, EdgeData>

the handler

Returns this

this core, for chaining

Example

const seen = [];
const handler = event => seen.push(event.target.id());
cy.one('example', node => node.isNode(), handler);
cy.getElementById('a').emit('example');
console.log(seen); // ['a']

Example graph and handle setup

Also spelled cy.once.

#cy.off(events, callback?)

// Remove a direct listener
cy.off(events: string, callback?: EventHandler<NodeData, EdgeData>): this

Stop listening. Removing a delegated handler takes the same ( events, predicate, handler) triple it was added with — predicates compare by function identity, so the predicate must be the same function object, not an equivalent one.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>?

the handler, when delegating

Returns this

this core, for chaining

Example

let count = 0;
const handler = () => count++;
cy.on('example', handler);
cy.off('example', handler);
cy.emit('example');
console.log(count); // 0

Example graph and handle setup

#cy.off(events, predicate, callback)

// Remove a delegated listener
cy.off(events: string, predicate: ElePredicate<NodeData, EdgeData>, callback: EventHandler<NodeData, EdgeData>): this

Remove a delegated handler. The predicate must be the same function object it was registered with — predicates compare by identity, not by structure.

Parameters
NameDescription
events: string

one or more space-separated event names

predicate: ElePredicate<NodeData, EdgeData>

the predicate the handler was added with

callback: EventHandler<NodeData, EdgeData>

the handler to remove

Returns this

this core, for chaining

Example

const seen = [];
const handler = event => seen.push(event.target.id());
cy.on('example', node => node.isNode(), handler);
const predicate = node => node.isNode();
cy.on('removed', predicate, handler);
cy.off('removed', predicate, handler);
cy.getElementById('a').emit('removed');
console.log(seen); // []

Example graph and handle setup

Also spelled cy.removeListener.

#cy.removeAllListeners()

// Remove all listeners
cy.removeAllListeners(): this

Remove every listener on the core, including element-bound and delegated ones.

Returns this

this core, for chaining

Example

let calls = 0;
cy.on('example', () => calls++);
cy.removeAllListeners();
cy.emit('example');
console.log(calls); // 0

Example graph and handle setup

#cy.emit(events, extraParams?)

// Emit an event on the core
cy.emit(events: string | EventProps, extraParams?: unknown[]): this

Emit an event on the core.

Custom event names are supported API, which is why on() validates none: cy.emit( 'myevent') runs handlers registered for 'myevent', and the same holds on elements. Names the library itself never emits are therefore legal to register and simply never fire — see on() for which those are.

Parameters
NameDescription
events: string | EventProps

one or more space-separated event names, or an event props object

extraParams: unknown[]?

extra arguments passed to each handler after the event object

Fields of events
NameDescription
type: string?
target: EventTarget?
cy: Core?
position: Position?

model-space position, for pointer-derived events

renderedPosition: Position?

rendered-space position; derived from position when omitted

originalEvent: NativeEvent?

the DOM event behind a gesture

layout: unknown?

the layout instance, on layoutstart/layoutready/layoutstop

cancelled: boolean?

on layoutstop: true when the run was abandoned by layout.cancel() or cy.destroy() rather than finished or stopped; on loadstop, when the load was cancelled

diff: PatchDiff?

on patch: what the patch added, removed and updated

progress: LoadProgress?

on loadstart/loadchunk/loadready/loadstop: how far the load has got

timeStamp: number?
Returns this

this core, for chaining

Example

let observed;
cy.one('example', event => { observed = event.type; });
cy.emit('example');
console.log(observed); // 'example'

Example graph and handle setup

Also spelled cy.trigger.

#cy.promiseOn(events, predicate?)

// Resolve once the next matching event fires — the promise form of one()
cy.promiseOn(events: string, predicate?: ElePredicate<NodeData, EdgeData>): Promise<Event<NodeData, EdgeData>>

Resolve once the next matching event fires — the promise form of one().

Parameters
NameDescription
events: string

one or more space-separated event names

predicate: ElePredicate<NodeData, EdgeData>?

an optional delegation predicate over the target

Returns Promise<Event<NodeData, EdgeData>>

a promise for the event object

Example

const next = cy.promiseOn('example');
cy.emit('example');
console.log((await next).type); // 'example'

Example graph and handle setup

Also spelled cy.pon.

All guides · Alphabetical API index · Read continuously