Skip to content

Events

Bind event handlers to each element in a collection.

#eles.on(events, callback?)

// Listen for events on each element of this collection
eles.on(events: string, callback?: EventHandler<NodeData, EdgeData>): this

Listen for events on each element of this collection. The handler is bound per element, and keeps firing across slot compaction — listeners repair with their elements rather than going stale.

Events bubble from an element through its compound ancestors to the core, with stopPropagation() honoured.

Any name registers, as on the core and for the same reason — custom events are supported API (ele.emit( 'foo')), so names cannot be gated. A name the library never emits fires only when your application emits it. Names match literally: 'data.ns' is distinct from 'data'. Raw mouse/touch names and vmouse* aliases are not emitted by the library. See Core#on.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>?

the handler

Returns this

this collection, for chaining

Example

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

Example graph and handle setup

Also spelled eles.addListener.

#eles.one(events, callback?)

// Like on(), but each element's handler runs at most once
eles.one(events: string, callback?: EventHandler<NodeData, EdgeData>): this

Like on(), but each element's handler runs at most once.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>?

the handler

Returns this

this collection, for chaining

Example

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

Example graph and handle setup

Also spelled eles.once.

#eles.off(events, callback?)

// Stop listening on each element of this collection
eles.off(events: string, callback?: EventHandler<NodeData, EdgeData>): this

Stop listening on each element of this collection.

Parameters
NameDescription
events: string

one or more space-separated event names

callback: EventHandler<NodeData, EdgeData>?

the handler to remove; omit to remove every handler these elements have for events

Returns this

this collection, for chaining

Example

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

Example graph and handle setup

Also spelled eles.removeListener.

#eles.emit(events, extraParams?)

// Emit an event on each element, bubbling through compound ancestors to the core
eles.emit(events: string, extraParams?: unknown[]): this

Emit an event on each element, bubbling through compound ancestors to the core.

Parameters
NameDescription
events: string

one or more space-separated event names

extraParams: unknown[]?

extra arguments passed to each handler after the event object

Returns this

this collection, for chaining

Example

cy.getElementById('a').one('example', event => console.log(event.type)); // "example"
cy.getElementById('a').emit('example'); // logs 'example'

Example graph and handle setup

Also spelled eles.trigger.

#eles.promiseOn(events)

// Resolve once the next matching event fires on any element of this collection — the promise form of one()
eles.promiseOn(events: string): Promise<Event<NodeData, EdgeData>>

Resolve once the next matching event fires on any element of this collection — the promise form of one().

Parameters
NameDescription
events: string

one or more space-separated event names

Returns Promise<Event<NodeData, EdgeData>>

a promise for the event object

Example

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

Example graph and handle setup

Also spelled eles.pon.

All guides · Alphabetical API index · Read continuously