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

npm install delegate-it

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

delegate('.btn', 'click', event => {
	console.log(event.delegateTarget); // The element matching '.btn' that was clicked
});

// Listen to multiple selectors
delegate(['.btn', '.link'], 'click', event => {
	console.log(event.delegateTarget);
});

// Listen to multiple event types
delegate('.btn', ['click', 'keypress'], event => {
	console.log(event.delegateTarget);
});

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

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')
});

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

controller.abort();

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

import {oneEvent} from 'delegate-it';

const event = await oneEvent('.btn', 'click');
console.log(event.delegateTarget); // The element matching '.btn' that was clicked

import {oneEvent} from 'delegate-it';

// Resolves only when a .btn with data-id="42" is clicked
const event = await oneEvent('.btn', 'click', {
	filter: event => event.delegateTarget.dataset.id === '42',
});

Attaches a delegated event listener. The actual listener is added to the base element (defaults to document.documentElement) and the callback is only called when the event's target matches selector.

Unlike raw addEventListener, identical listeners (same selector, type, callback, and capture value) are not added multiple times.

Type: string | string[]

A CSS selector string or array of CSS selector strings to match against. The callback is called when the event target (or one of its ancestors) matches the selector and is a descendant of base.

Type: string | string[]

The event type (e.g. 'click') or array of event types to listen for.

Type: (event: DelegateEvent) => void

The function to call when the event is triggered. Receives a DelegateEvent — a standard Event with an added delegateTarget property.

Type: DelegateOptions

Optional object extending AddEventListenerOptions with one extra field:

Returns a Promise that resolves with the first matching DelegateEvent. Useful as an alternative to delegate with {once: true}.

If the signal is already aborted when oneEvent is called, or is aborted before the event fires, the promise resolves with undefined.

import {oneEvent} from 'delegate-it';

const event = await oneEvent('.btn', 'click');
// event is a DelegateEvent, or undefined if the signal was aborted

Type: string | string[]

A CSS selector string or array of CSS selector strings.

Type: string

The event type to listen for.

Type: OneEventOptions

Same as delegate options, minus once (which is always set automatically), plus:

A regular DOM Event extended with one additional property:

Type: Element

The element that matched the selector. This is different from event.target, which is the innermost element that was actually interacted with (e.g. a <span> inside a <button>), while delegateTarget is always the element matching the selector (e.g. the <button> itself).

delegate('.btn', 'click', event => {
	event.target;         // e.g. <span> inside the button
	event.delegateTarget; // always the <button> matching '.btn'
});

The type of event.delegateTarget is inferred from selector when possible, using typed-query-selector. For example, delegate('button', 'click', ...) will type event.delegateTarget as HTMLButtonElement automatically.

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:toggle'.

import type {EventType} from 'delegate-it';

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

• 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.