Query - Events

Attach, remove, and trigger events on elements.

Binding Events

on

$('selector').on(eventName, handler, options);

Attaches an event listener to matched elements.

Parameters

Options

Returns

• Standard: Query object (for chaining)
• returnHandler: true: Handler object with abort() method (example)

Usage

$('button').on('click', (e) => {
  console.log('Clicked!', e.target);
});

Handler Return Values

Handlers can use return values to control event propagation:

• return false — calls stopPropagation(), preventing the event from reaching other handlers
• return 'cancel' — calls preventDefault(), canceling the browser’s default action

// Stop the event from bubbling to parent handlers
$('span').on('click', (e) => {
  return false;
});

// Prevent the browser's default action (e.g., form submission)
$('form').on('submit', (e) => {
  if (!isValid()) {
    return 'cancel';
  }
});

Example

off

$('selector').off(eventName, handler);

Removes event handlers attached with on().

Parameters

Returns

Query object (for chaining).

Usage

const handler = (e) => console.log('Clicked!');

$('button').on('click', handler);
$('button').off('click', handler);

Example

one

$('selector').one(eventName, handler);

Attaches a handler that executes at most once per element.

Parameters

Returns

Query object (for chaining).

Usage

$('button').one('click', () => {
  console.log('This fires once only');
});

Example

intercept

$('selector').intercept(eventName, handler);
$('selector').intercept(eventName, delegateSelector, handler);

Attaches a capture-phase event listener. Events fire top-down during capture (parent first), unlike on() which fires bottom-up during bubbling (child first). Use intercept when a parent needs to handle or block an event before children see it.

Parameters

Returns

Query object (for chaining).

Usage

// Parent intercepts ESC before children handle it
$('.modal').intercept('keydown', (e) => {
  if (e.key === 'Escape') {
    closeModal();
    return false; // children never see this event
  }
});

// With delegation
$('.form').intercept('click', '[type="submit"]', function(e) {
  if (!isValid()) {
    return false; // button's own handler never fires
  }
});

Example

onNext

$('selector').onNext(eventName);
$('selector').onNext(eventName, delegateSelector);
$('selector').onNext(eventName, options);

Returns a Promise that resolves on the next event occurrence. Useful for async/await patterns.

Parameters

Returns

Promise that resolves with the event object.

Usage

await $('button').onNext('click');
console.log('Button was clicked!');

Event Delegation

Event delegation attaches a handler to a parent element that fires when descendants match a selector. Works with dynamically added elements.

on (delegated)

$('selector').on(eventName, delegateSelector, handler, options);

Parameters

Returns

Query object (for chaining).

Usage

$('#container').on('click', 'button', (e) => {
  console.log('Button clicked!', e.target);
});

Example

Triggering Events

trigger

$('selector').trigger(eventName);

Executes all handlers for the given event type.

Parameters

Returns

Query object (for chaining).

Usage

$('button').trigger('click');

Example

dispatchEvent

$('selector').dispatchEvent(eventName, eventData, eventSettings);

Creates and dispatches a custom event.

Parameters

Returns

Query object (for chaining).

Usage

Dispatch

$('.container').dispatchEvent('resize', { delta: 100 });

Listen

$('.container').on('resize', (e) => {
  console.log('Delta:', e.detail.delta);
});

Example

Shorthand

focus

$('selector').focus();

Gives focus to the first matched element.

Returns

Query object (for chaining).

Usage

$('input.username').focus();

Example

blur

$('selector').blur();

Removes focus from the first matched element.

Returns

Query object (for chaining).

Usage

$(document.activeElement).blur();

Example

click

$('selector').click();

Triggers a click event on matched elements.

Returns

Query object (for chaining).

Usage

$('button.submit').click();

Example

submit

$('selector').submit();

Triggers a submit event on matched form elements.

Returns

Query object (for chaining).

Usage

$('form').submit();

Example

ready

$(document).ready(handler);

Executes a function when the DOM is fully loaded.

Parameters

Returns

Query object (for chaining).

Usage

$(document).ready(() => {
  console.log('DOM ready!');
});

Example