Delegate

Efficient event delegation that attaches a single listener to a root element and matches child elements via CSS selectors. Ideal for handling events on dynamically rendered content. Access via Aura.delegate after calling Aura.init().

Quick Start

js
import Aura from 'aura.js';

Aura.init();

// Delegate click events to all buttons inside the app container
Aura.delegate.on('click', '.btn', (event, target) => {
  console.log('Clicked:', target.textContent);
});

// Handle form submissions once
Aura.delegate.once('submit', 'form.signup', (event, target) => {
  event.preventDefault();
  submitForm(target);
});

// Clean up all listeners
Aura.delegate.destroy();

How It Works

When you call Aura.init(), an AuraDelegate instance is created and bound to the app container element. Instead of attaching event listeners to every individual child element, a single listener is placed on the container. When an event fires, the delegate checks if event.target matches your CSS selector using Element.closest(), and only calls your handler if there is a match within the container.

This pattern is especially useful when DOM content is dynamically rendered (e.g. by the router or template engine), since listeners survive re-renders without needing to be re-attached.

on()

Registers a delegated event handler. The handler fires every time the event occurs on an element matching the selector within the root container. Returns an unsubscribe function.

on(eventType: string, selector: string, handler: (event: Event, target: Element) => void): () => void

Param	Type	Description
eventType	string	The DOM event type, e.g. `'click'`, `'input'`, `'submit'`
selector	string	A CSS selector to match against, e.g. `'.btn'`, `'[data-action]'`
handler	(event, target) => void	Callback receiving the original Event and the matched Element

js
// Handle clicks on list items
const unsub = Aura.delegate.on('click', 'li.todo-item', (event, target) => {
  target.classList.toggle('completed');
});

// Handle input on any text field
Aura.delegate.on('input', 'input[type="text"]', (event, target) => {
  console.log('Value:', target.value);
});

// Use data attributes for flexible delegation
Aura.delegate.on('click', '[data-action="delete"]', (event, target) => {
  const id = target.dataset.id;
  deleteItem(id);
});

// Unsubscribe later
unsub();

once()

Registers a delegated event handler that fires only once. After the first matching event, the handler is automatically removed. Returns an unsubscribe function in case you want to remove it before it fires.

once(eventType: string, selector: string, handler: (event: Event, target: Element) => void): () => void

Param	Type	Description
eventType	string	The DOM event type
selector	string	A CSS selector to match against
handler	(event, target) => void	Callback receiving the original Event and the matched Element

js
// Show a welcome modal only the first time a user clicks "Get Started"
Aura.delegate.once('click', '.get-started-btn', (event, target) => {
  showWelcomeModal();
});

// Can still unsubscribe before it fires
const cancel = Aura.delegate.once('submit', 'form', (event) => {
  event.preventDefault();
});
cancel(); // removes before it ever fires

off()

Removes delegated event handlers. Can be called in three ways:

off(eventType) — removes all handlers for that event type
off(eventType, selector) — removes handlers matching the selector string
off(eventType, handler) — removes the specific handler function reference

off(eventType: string, selectorOrHandler?: string | DelegateHandler): void

Param	Type	Description
eventType	string	The DOM event type to remove handlers for
selectorOrHandler	string \| Function	Optional. A CSS selector string or the handler function reference to remove. Omit to remove all handlers for the event type.

js
// Remove all click handlers
Aura.delegate.off('click');

// Remove handlers for a specific selector
Aura.delegate.off('click', '.btn');

// Remove a specific handler by reference
const myHandler = (event, target) => { /* ... */ };
Aura.delegate.on('click', '.btn', myHandler);
Aura.delegate.off('click', myHandler);

destroy()

Removes all delegated event handlers for all event types and clears internal state. Call this when tearing down your application or before reinitializing.

destroy(): void

js
// Tear down all delegation
Aura.delegate.destroy();

// Typical usage: clean up on page leave
Aura.on('route:leave', () => {
  Aura.delegate.destroy();
});