readme.md

delegate-it

Lightweight event delegation

This is a fork of the popular but abandoned delegate with some improvements:

• modern: ES2022, TypeScript, Edge 16+ (it uses WeakMap and Element.closest())
• idempotent: identical listeners aren't added multiple times, just like the native addEventListener
• debugged (2d54c11, c6bb88c)
• supports AbortSignal

Install

npm install delegate-it

// This module is only offered as a ES Module
import delegate from 'delegate-it';

Usage

Add event delegation

delegate('.btn', 'click', event => {
	console.log(event.delegateTarget);
});

With listener options

delegate('.btn', 'click', event => {
	console.log(event.delegateTarget);
}, {
	capture: true
});

On a custom base

Use this option if you don't want to have a global listener attached on html, it improves performance:

delegate('.btn', 'click', event => {
	console.log(event.delegateTarget);
}, {
	base: document.querySelector('main')
});

Remove event delegation

const controller = new AbortController();
delegate('.btn', 'click', event => {
	console.log(event.delegateTarget);
}, {
	signal: controller.signal,
});

controller.abort();

Listen to one event only

delegate('.btn', 'click', event => {
	console.log('This will only be called once');
}, {
	once: true
});

Listen to one event only, with a promise

import {oneEvent} from 'delegate-it';

await oneEvent('.btn', 'click');
console.log('The body was clicked');

TypeScript

If you're using TypeScript and have event types that are custom, you can override the global GlobalEventHandlersEventMap interface via declaration merging. e.g. say you have a types/globals.d.ts file, you can add the following.

interface GlobalEventHandlersEventMap {
	'details:toggle': UIEvent;
}

In the file that imports EventType, you will now be able to set the event type to 'details:toggled'.

import {EventType} from 'delegate-it';

const someEventType1: EventType = 'details:toggled'; // all good
const someEventType2: EventType = 'click'; // all good
const someEventType3: EventType = 'some-invalid-event-type'; // no good

Related

• select-dom - Lightweight querySelector/All wrapper that outputs an Array.
• doma - Parse an HTML string into DocumentFragment or one Element, in a few bytes.
• Refined GitHub - Uses this module.