A lightweight, flexible event delegation utility for modern web applications. Simplifies event management by centralizing listeners and providing advanced routing options.
YpsilonEventHandler uses browser-native APIs (stable since 2000) for reliable, no-dependency event handling. Works on file:// with zero build tools.
- Event Delegation Made Easy: One listener handles dynamic elements with scope-based routing.
- Automatic Target Resolution: Handles nested elements (e.g., SVGs in buttons).
- Throttle & Debounce Support: Built-in performance controls.
- Dynamic Listener Management: Add/remove events at runtime.
- Flexible Handler Resolution: Class methods, external maps, or globals.
- Multi-Handler System: Closest-match resolution for nested components.
- Performance Tracking: Optional metrics for optimization.
- No Dependencies: ~5kB gzipped, enterprise-ready (~800 LOC).
For advanced patterns (e.g., reactive state, super delegation), see README.USAGE.md. For internals, see README.TECHNICAL.md.
No setup, no build step, no server, just include the file.
Get started in 30 seconds – try it live on JSFiddle
<!DOCTYPE html>
<html>
<head><title>YEH Demo</title></head>
<body>
<div id="app">
<button data-action="save">Save</button>
<button data-action="delete">Delete</button>
</div>
<script src="https://cdn.jsdelivr.net/npm/ypsilon-event-handler@latest"></script>
<script>
class MyHandler extends YpsilonEventHandler {
constructor() {
super({ '#app': ['click'] }); // Falls back to handleClick()
}
handleClick(event, target) {
const action = target.dataset.action;
if (action && this[action]) this[action](target, event);
}
save(target) { console.log('Saving...'); }
delete(target) { console.log('Deleting...'); }
}
new MyHandler(); // Adding listeners Done
</script>
</body>
</html>30-second setup: Create app.html, copy & paste the above code, then double-click to run.
💡 Universal Delegation Pattern
One listener on parent +
custom-selector= handles unlimited elements within the parent
<script src="https://cdn.jsdelivr.net/npm/ypsilon-event-handler@1.8.2/ypsilon-event-handler.min.js"></script>npm install ypsilon-event-handlerDownload latest version - works with file:// protocol
Pass a third argument to the constructor to enable advanced features:
| Option | Type | Default | Description |
|---|---|---|---|
enableStats |
boolean |
false |
Track performance metrics like event count and distance cache hits. |
methods |
object |
null |
External method map for organizing handlers by event type. |
enableGlobalFallback |
boolean |
false |
Fallback to global window functions when no method is found. |
methodsFirst |
boolean |
false |
Check methods object before class methods during handler resolution. |
passiveEvents |
array |
auto | Override default passive events (scroll, touch, wheel, pointer). |
abortController |
boolean |
false |
Enable AbortController support for programmatic listener removal. |
enableDistanceCache |
boolean |
true |
Cache DOM distance calculations for performance (multi-handler scenarios). |
Example: new YpsilonEventHandler(events, aliases, { enableStats: true });
Chain operations for complex event orchestration:
App.on('data-ready', 'handleData')
.on('user-login', 'handleLogin')
.emit('init-complete', { loaded: true });handler.destroy(); or handler.abort(); (if enabled).
With enableStats: true: console.log(handler.getStats());
Chrome | Firefox | Safari | Edge - all modern versions
Works with legacy browsers via Webpack + Babel.
| Feature | YpsilonEventHandler | EventEmitter3 | Redux Toolkit | jQuery |
|---|---|---|---|---|
| Bundle Size | 5kB gzipped | 7kB gzipped | 12kB+ gzipped | 30kB+ gzipped |
| Dependencies | ✅ Zero | ✅ Zero | ❌ Many | ✅ Zero |
| Event Delegation | ✅ Advanced | ❌ None | ❌ None | ✅ Basic |
| Multi-Handler System | ✅ Unique | ❌ None | ❌ None | ❌ None |
| Throttle/Debounce | ✅ Built-in | ❌ None | ❌ None | ❌ None |
| Native Browser API | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Dynamic Element Support | ✅ Zero-config | ❌ None | ❌ None | ✅ Re-bind |
| TypeScript Support | ✅ Full | ✅ Partial | ✅ Full | |
| Memory Leak Prevention | ✅ Automatic | ✅ Automatic | ||
| Performance | ✅ Native | |||
| Custom Event Dispatch | ✅ Built-in | ✅ Yes | ✅ Yes | ✅ Yes |
| Learning Curve | ✅ Low | ✅ Low | ❌ Steep | ✅ Familiar |
- Smallest footprint with advanced features like multi-handler delegation.
- Native performance using browser APIs, avoiding synthetic event overhead.
- Zero dependencies and automatic memory management for scalability.
- Built-in utilities (throttle, debounce, stats) eliminate external needs.
Interactive Examples Hub ~ Beautiful landing page with all examples organized by category
Feature Demonstrations ~ Interactive examples of specific capabilities
/
├── ypsilon-event-handler.js # Main library
├── README.md # Quick start and core guide
├── README.USAGE.md # Advanced patterns and techniques
└── README.TECHNICAL.md # Implementation details and architectureMIT License – free to use in personal or commercial projects.
- Claude Van DOM - Implementation and optimization
- Engin Ypsilon - Original concept and architecture
- The Y-Team - Sunny DeepSeek & Herr Von Grokk