.on | Auto-cleaned event listeners for the DOM

.on(type, fn?, opts?)

Available on: InDom, InDomArray

Registers an event listener that is automatically removed when the element is removed from the DOM (no matter how) , preventing memory leaks.

Parameters:

type {string | string[]} - Event type, e.g. 'click', 'keydown' or array of event types

fn {(n: InDom, e: Event) => void} (optional) - Event handler. Omit for mouse/click to trigger the event

opts {AddEventListenerOptions} (optional) - Event options (once, passive, etc.)

Returns: {Function | Function[]} - The internal handler(s) – pass to .off() to remove manually

Throws:

Error - If the underlying element is not connected to DOM, or document not yet loaded

Error - If the underlying element(s) has been removed

Error - If auto-trigger is used with non-mouse event

TypeError - If handler is not a function (when provided)

Shorthand methods:

onClick(fn?, opts?) → .on('click', fn, opts)

onDoubleClick(fn?, opts?) → .on('dblclick', fn, opts)

onEnter(fn?, opts?) → .on('mouseenter', fn, opts)

onLeave(fn?, opts?) → .on('mouseleave', fn, opts)

onFocus(fn?, opts?) → .on('focus', fn, opts)

onBlur(fn?, opts?) → .on('blur', fn, opts)

onChange(fn?, opts?) → .on('change', fn, opts)

once(type, fn, opts?) → .on(type, fn, { ...opts, once: true })

Examples:

// log every keypress in username / message fields
$a('[name="username"], [name="message"]').on('keydown', (n, e) => {
	console.log(`name:${n.getAttr('name')} , key pressed:${e.key} 
		, current value:${n.getValue()}`);
	if (e.key === 's') {
		e.preventDefault(); // block 's' key
	}
});

// add / remove hover class on every .example>div
$a('.example>div').onEnter(n => n.addClass('on'));
$a(".example>div").onLeave(n => n.removeClass('on'));

// simple accordion: only one panel open at a time
const menu = $1('#menu');
const menuBtn = $1('>.btn', menu);
const search = $1('#search');
const searchBtn = $1('>.btn', search);

menuBtn.onClick(() => {
	if (menu.hasClass('on')) { menu.removeClass('on'); return; }
	if (search.hasClass('on')) { searchBtn.onClick(); } // close other
	menu.addClass('on');
});

searchBtn.onClick(() => {
	if (search.hasClass('on')) { search.removeClass('on'); return; }
	if (menu.hasClass('on')) { menuBtn.onClick(); } // close other
	search.addClass('on');
});

// clicking anywhere adds 'clicked' class to the clicked element
$n(document).onClick((_, e) => $n(e.target).addClass('clicked'));

// 'on' can also accept many event types for the same handler 
// here is a simple throttle example
let canClick = true;
$1(".example>div").on(["click", "touchstart"], n => {
	if (!canClick) {
		return;
	}
	canClick = false;
	console.log(n); // do something
	setTimeout(() => canClick = true, 300);
});

Next: onRemove »