signalizejs/event

Installation

• mutation-observer

const {
	off,
	on,
	customEvent,
	customEventListener,
	dispatch
} = await signalize.resolve('event');

API

on

Attach a listener to elements or listen to dispatched events.

Listeners are automatically attached to dynamically added elements if the second argument is a string selector.

// Listen to globally dispatched event on the root element
on('custom:event', () => {});

// Bind listener directly to an existing element
on('click', document.querySelector('#element'), () => {});

// Bind listener globally, works on dynamically added elements
on('click', '.element', () => {});

// Bind two events to already existing elements
on('click mouseover', document.querySelectorAll('.element'), () => {});

// Bind two events to already existing elements with options
on('click mouseover', document.querySelectorAll('.element'), () => {}, {
	// Default false
	passive: true,
	// Default false
	once: true
});

The on function also automatically prepares a function that will remove the defined listener, so you don’t have to prepare it yourself:

const removeListener = on('click', '.selector', () => alert('Hello World'));

// This will remove the defined click listener above.
removeListener();

off

Remove an event listener or listeners from one or more elements.

// Bind listener directly to an existing element
const handler = () => alert('Hello World!');
const element = document.querySelector('#element');

// Remove handler from the existing element
off('click', element, handler);

// Remove handler from all elements globally
off('click', '.element', handler);

// Remove two event listeners from already existing elements
off('click mouseover', [element], handler);

customEventListener

Create a custom event listener.

customEventListener('clickOutside', () => {
	return {
		on: ({ listener, target, options }) => {},
		off: ({ listener, target, options }) => {}
	}
});

/*
 Before the "listener" callback is attached to a custom event listener event as an argument,
 there is a check if the event should be triggered only once (once: true).

 If so, the "off" callback of the custom event listener is called automatically
 after the first call if it is defined. You don't have to program it yourself.

 This keeps the behavior similar to the native once: true option.
 You should always consider the possibility of removing the event listener.
*/
on('clickOutside', element, () => {
	// This will be triggered only once and automatically removed
}, { once: true })

customEvent

Create a custom event you can later dispatch.

Internaly uses native CustomEvent.

const myEvent = customEvent(
	'my-event',
	// Optional
	{ /* data*/ },
	// Native custom event options - example with defaults
	{
		cancellable: false,
		bubbles: false
	}
);

document.dispatchEvent(myEvent);

dispatch

Create and dispatches a CustomEvent to the target element.

// Dispatch event to the configured root element
dispatch('my-event');

// Dispatch event with custom data
dispatch('my-event', data)

// Dispatch event to selected element.
dispatch('my-event', data, element)