Skip to content

on ​

The on function registers a delegated event listener that fires whenever an event reaches an element matching the selector - including elements added to the DOM after on was called.

Usage ​

A single document-level listener is shared across every on(eventName, ...) call with the same capture and passive options, so registering many handlers does not multiply the number of native listeners. When the event fires, ancestors of event.target are walked and callback is invoked once per matching ancestor with event.currentTarget set to the matched element.

ts
import { on } from '@ambiki/impulse';

// Listen for clicks on every button - including ones inserted later
on('click', 'button', (event) => {
  console.log('Button clicked: ', event.currentTarget);
});

Event listener options ​

You can pass the standard event listener options: capture, once, passive, and signal.

ts
// Fire the event listener only once across the entire document
on('click', '.once-button', (event) => {
  console.log('Clicked once');
}, { once: true });

// Use capture phase
on('click', '.capture-host', (event) => {
  console.log('Captured');
}, { capture: true });

// Mark the shared document listener as passive
on('touchstart', '.swipe-area', (event) => {
  console.log('Touch started');
}, { passive: true });

// Tie the registration to an AbortSignal
const controller = new AbortController();
on('click', 'button', (event) => {
  console.log('Clicked');
}, { signal: controller.signal });

A once handler is removed before its callback runs, so it fires at most once even if the callback throws or re-dispatches the same event. passive is forwarded to the shared document listener, so passive and non-passive registrations for the same event use separate listeners. Aborting signal removes the registration exactly as calling the returned cleanup would; a signal that is already aborted skips registration entirely.

Non-bubbling events ​

Because dispatch flows through a single document listener, events that do not bubble (focus, blur, mouseenter, mouseleave, load, error, scroll) will not reach the listener unless you opt into the capture phase. Prefer the bubbling counterparts (focusin, focusout, mouseover, mouseout) when possible:

ts
// Both work, but the second avoids the capture-phase opt-in
on('focus', 'input', handler, { capture: true });
on('focusin', 'input', handler);

Propagation ​

Calling event.stopPropagation() inside a handler halts further delegated dispatch on the same event - handlers matched on elements later in the walk will not fire: ancestors when bubbling, descendants with capture. event.stopImmediatePropagation() additionally blocks any remaining handlers registered against the same element.

Without capture, every handler runs from a bubbling listener on document, so the event has already passed through the elements in between. event.stopPropagation() in such a handler cannot stop a native listener on one of those elements, and a native listener that stops propagation before the event reaches document keeps every bubbling on handler from running.

Errors ​

A selector the browser rejects throws a DOMException named SyntaxError at the call and registers nothing, even when signal is already aborted.

A handler that throws is reported like an uncaught error, so it reaches window.onerror, and does not stop the handlers after it - the same way the browser isolates native listeners from one another.

Stopping observation ​

The on function returns a cleanup function that detaches the handler. The same detachment happens when a once handler fires or when the signal passed in the options aborts. The shared document listener is removed once the last handler for that event name (and capture / passive options) is detached.

ts
const stop = on('click', 'button', (event) => {
  console.log('Clicked');
});

// Later, remove the handler
stop();

Released under the MIT License.